Skip to content

Commit

Permalink
Update ARIA12 (#3734)
Browse files Browse the repository at this point in the history 
Closes #3733 

- Specify that `aria-level` must be used.
- Update examples to use `aria-level`.
- Remove link to APG as the referenced content isn’t there anymore.
- Update test procedure for `aria-level`.
- Add note about `aria-level` values of 10 and greater.
- Add link to `aria-level` spec.
- Add link to HTML headings spec.

---------

Co-authored-by: Patrick H. Lauke <redux@splintered.co.uk>
Co-authored-by: Alastair Campbell <ac@alastc.com>
Co-authored-by: Scott O'Hara <scottaohara@users.noreply.github.com>
  • Loading branch information
@fstrr @patrickhlauke
@alastc @scottaohara
4 people committed Apr 30, 2024
1 parent 29d84ee commit 21158e1
Showing 1 changed file with 74 additions and 52 deletions.
126 changes: 74 additions & 52 deletions techniques/aria/ARIA12.html
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,37 @@
<!DOCTYPE html><html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"><head><title>Using role=heading to identify headings</title><link rel="stylesheet" type="text/css" href="../../css/editors.css" class="remove"/></head><body><h1>Using role=heading to identify headings</h1><section class="meta"><p class="id">ID: ARIA12</p><p class="technology">Technology: aria</p><p class="type">Type: Technique</p></section><section id="applicability"><h2>When to Use</h2>
<!DOCTYPE html>
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Using role=heading to identify headings</title>
<link rel="stylesheet" type="text/css" href="../../css/editors.css" class="remove">
</head>
<body>
<h1>Using <code class="language-html">role=heading</code> to identify headings</h1>
<section class="meta">
<p class="id">ID: ARIA12</p>
<p class="technology">Technology: aria</p>
<p class="type">Type: Technique</p>
</section>
<section id="applicability">
<h2>When to Use</h2>
<p>Technologies that support <a href="https://www.w3.org/TR/wai-aria/">Accessible Rich Internet Applications (WAI-ARIA)</a>. </p>
</section><section id="description"><h2>Description</h2>
</section>
<section id="description">
<h2>Description</h2>
<p>The purpose of this technique is to provide a way for Assistive Technologies (AT) to identify
a piece of content as a heading. Applying <code class="language-html">role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading.
</p>
<p>If there is more than one heading on the page and the heading hierarchy is defined through the
visual presentation, the <code class="language-html">aria-level</code> attribute should be used to indicate the hierarchical level of the heading. </p>
<p>When possible, use native heading mark-up directly. For example, it is preferable
to use <code class="language-html">h1</code> rather than using <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code>. However, the use of the
heading role, instead of heading mark-up, may be necessary. For example, when retrofitting a legacy site where scripts depend on the existing element hierarchy.
</p>
<p>The use of the <code class="language-html">heading</code> role and nesting levels is discussed in <a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>.
</p>
</section><section id="examples"><h2>Examples</h2>
<section class="example">
<h3>Simple headings</h3>

<p>This example demonstrates how to implement simple headings using <code class="language-html">role="heading"</code> when retrofitting a legacy site where scripts depend on the existing element hierarchy or the level is unknown. For example, web content which is syndicated from various sources may be constructed without knowledge of what the final presentation will be.
</p>
<pre xml:space="preserve"><code class="language-html">&lt;div role="heading"&gt;Global News items&lt;/div&gt;
a piece of content as a heading. Applying <code class="language-html">role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading. The <code class="language-html">role="heading"</code> property must be paired with the <code class="language-html">aria-level</code> property to define the heading level.</p>
<p>When possible, <a href="https://www.w3.org/TR/using-aria/#rule1">use native heading markup</a>. For example, it is preferable to use an <code class="language-html">h1</code> element, rather than using <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code>. Native <abbr title="HyperText Markup Language">HTML</abbr> elements have implicit styling and features that won't necessarily be replicated with ARIA equivalents. For instance, heading elements will have specific styling adjustments made when viewing a page in a browser's Reader Mode. Whereas a <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code> will not be styled as a heading, because the underlying element is a <code class="language-html">div</code>. ARIA only modifies the way an element is exposed to assistive technology, it does nothing to change the implicit style or functionality of the element it is applied to.</p>

</section>
<section id="examples">
<h2>Examples</h2>
<section class="example">
<h3>Simple headings</h3>
<p>This example demonstrates how to implement headings using <code class="language-html">role="heading"</code> and <code class="language-html">aria-level</code>.</p>
<pre xml:space="preserve"><code class="language-html">&lt;div role="heading" aria-level="2"&gt;Global News Items&lt;/div&gt;
... a list of global news with editorial comment....

&lt;div role="heading"&gt;Local News items&lt;/div&gt;
... a list of local news, with editorial comment ...</code></pre>

&lt;div role="heading" aria-level="3"&gt;Politics&lt;/div&gt;
... a list of global political news stories ...</code></pre>
</section>
<section class="example">
<h3>Additional heading levels</h3>
Expand All @@ -33,41 +41,55 @@ <h3>Additional heading levels</h3>
&lt;h6&gt;Apples&lt;/h6&gt;
&lt;p&gt;Apples grow on trees in areas known as orchards...&lt;/p&gt;
...
&lt;div role="heading" aria-level="7"&gt;Jonagold/div&gt;
&lt;div role="heading" aria-level="7"&gt;Jonagold&lt;/div&gt;
&lt;p&gt;Jonagold is a cross between the Golden Delicious and Jonathan varieties...&lt;/p&gt;</code></pre>

</section>
</section><section id="tests"><h2>Tests</h2>
<section class="procedure"><h3>Procedure</h3>
<ol>
<li> Examine each element with the attribute <code class="language-html">role="heading"</code>.
</li>
<li> Determine whether the content of the element is appropriate as a heading.
</li>
<li> If the element has an <code class="language-html">aria-level</code> attribute, determine whether the value is the appropriate hierarchical level.
</li>
</ol>
<aside class="note">
<p>Headings with an <code class="language-html">aria-level</code> of 10 or higher can create difficulties for users. At the time of writing (2024), most combinations of user agents and assistive technologies report such levels as being level 2.</p>
</aside>
</section>
<section class="results"><h3>Expected Results</h3>
<ul>
<li>#2 and #3 are true.</li>
</ul>
</section>
<section id="tests">
<h2>Tests</h2>
<section class="procedure">
<h3>Procedure</h3>
<ol>
<li>Examine each element with the attribute <code class="language-html">role="heading"</code>.</li>
<li>Determine whether the content of the element is appropriate as a heading.</li>
<li>Determine whether the <code class="language-html">aria-level</code> value is the appropriate hierarchical level.</li>
</ol>
</section>
<section class="results">
<h3>Expected Results</h3>
<ul>
<li>#2 and #3 are true.</li>
</ul>
</section>
</section><section id="related"><h2>Related Techniques</h2><ul>
</section>
<section id="related">
<h2>Related Techniques</h2>
<ul>
<li><a href="../html/H42">H42</a></li>
<li><a href="../html/H69">H69</a></li>
<li><a href="../general/G141">G141</a></li>
<li><a href="../failures/F2">F2</a></li>
</ul></section><section id="resources"><h2>Resources</h2>

<ul>
<li>
<a href="https://www.w3.org/TR/wai-aria/#heading">Accessible Rich Internet Applications (WAI-ARIA), Heading in the Roles Model</a>
</li>
<li>
<a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>
</li>
</ul>

</ul>
</section>
<section id="resources">
<h2>Resources</h2>
<ul>
<li>
<a href="https://www.w3.org/TR/wai-aria/#heading">Accessible Rich Internet Applications (WAI-ARIA), <code class="language-html">heading</code> role.</a>
</li>
<li>
<a href="https://www.w3.org/TR/wai-aria/#aria-level">Accessible Rich Internet Applications (WAI-ARIA), <code class="language-html">aria-level</code> property.</a>
</li>
<li>
<a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>
</li>
<li>
<a href="https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements">HTML, the <code class="language-html">h1</code>, <code class="language-html">h2</code>, <code class="language-html">h3</code>, <code class="language-html">h4</code>, <code class="language-html">h5</code>, and <code class="language-html">h6</code> elements</a>.
</li>
</ul>
</section>
</body></html>
</body>
</html>

0 comments on commit 21158e1

Please sign in to comment.