You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
<p>The purpose of this technique is to provide a way for Assistive Technologies (AT) to identify
5
-
a piece of content as a heading. Applying <codeclass="language-html">role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading.
6
-
</p>
7
-
<p>If there is more than one heading on the page and the heading hierarchy is defined through the
8
-
visual presentation, the <codeclass="language-html">aria-level</code> attribute should be used to indicate the hierarchical level of the heading. </p>
9
-
<p>When possible, use native heading mark-up directly. For example, it is preferable
10
-
to use <codeclass="language-html">h1</code> rather than using <codeclass="language-html"><div role="heading" aria-level="1"></code>. However, the use of the
11
-
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.
12
-
</p>
13
-
<p>The use of the <codeclass="language-html">heading</code> role and nesting levels is discussed in <ahref="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>.
14
-
</p>
15
-
</section><sectionid="examples"><h2>Examples</h2>
16
-
<sectionclass="example">
17
-
<h3>Simple headings</h3>
18
-
19
-
<p>This example demonstrates how to implement simple headings using <codeclass="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.
a piece of content as a heading. Applying <codeclass="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 <codeclass="language-html">role="heading"</code> property must be paired with the <codeclass="language-html">aria-level</code> property to define the heading level.</p>
22
+
<p>When possible, <ahref="https://www.w3.org/TR/using-aria/#rule1">use native heading markup</a>. For example, it is preferable to use an <codeclass="language-html">h1</code> element, rather than using <codeclass="language-html"><div role="heading" aria-level="1"></code>. Native <abbrtitle="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 <codeclass="language-html"><div role="heading" aria-level="1"></code> will not be styled as a heading, because the underlying element is a <codeclass="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>
23
+
24
+
</section>
25
+
<sectionid="examples">
26
+
<h2>Examples</h2>
27
+
<sectionclass="example">
28
+
<h3>Simple headings</h3>
29
+
<p>This example demonstrates how to implement headings using <codeclass="language-html">role="heading"</code> and <codeclass="language-html">aria-level</code>.</p>
<p>Jonagold is a cross between the Golden Delicious and Jonathan varieties...</p></code></pre>
38
-
39
-
</section>
40
-
</section><sectionid="tests"><h2>Tests</h2>
41
-
<sectionclass="procedure"><h3>Procedure</h3>
42
-
<ol>
43
-
<li> Examine each element with the attribute <codeclass="language-html">role="heading"</code>.
44
-
</li>
45
-
<li> Determine whether the content of the element is appropriate as a heading.
46
-
</li>
47
-
<li> If the element has an <codeclass="language-html">aria-level</code> attribute, determine whether the value is the appropriate hierarchical level.
48
-
</li>
49
-
</ol>
46
+
<asideclass="note">
47
+
<p>Headings with an <codeclass="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>
48
+
</aside>
50
49
</section>
51
-
<sectionclass="results"><h3>Expected Results</h3>
52
-
<ul>
53
-
<li>#2 and #3 are true.</li>
54
-
</ul>
50
+
</section>
51
+
<sectionid="tests">
52
+
<h2>Tests</h2>
53
+
<sectionclass="procedure">
54
+
<h3>Procedure</h3>
55
+
<ol>
56
+
<li>Examine each element with the attribute <codeclass="language-html">role="heading"</code>.</li>
57
+
<li>Determine whether the content of the element is appropriate as a heading.</li>
58
+
<li>Determine whether the <codeclass="language-html">aria-level</code> value is the appropriate hierarchical level.</li>
<ahref="https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements">HTML, the <codeclass="language-html">h1</code>, <codeclass="language-html">h2</code>, <codeclass="language-html">h3</code>, <codeclass="language-html">h4</code>, <codeclass="language-html">h5</code>, and <codeclass="language-html">h6</code> elements</a>.
0 commit comments