Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update ARIA12 #3734

Merged
merged 5 commits into from
Apr 30, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 74 additions & 52 deletions techniques/aria/ARIA12.html
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 mark-up</a>. 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 <abbr title="HyperText Markup Language">HTML</abbr>, may be necessary.</p>
fstrr marked this conversation as resolved.
Show resolved Hide resolved

</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, most combinations of user agents and assistive technologies report such levels as being level 2.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems really odd to me. Is there a reference?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mentioned it in the issue—I found it in the ARIA 1.3 draft and tweaked it a bit.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also discussed in this week's backlog meeting, here's a reference CodePen so you can test this yourself should you wish :)

fstrr marked this conversation as resolved.
Show resolved Hide resolved
</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>