Skip to content

Commit 4dcd209

Browse files
spectranautmcking65
spectranaut
authored and
mcking65
committed
Initial draft of guidelines for aria-level attribute (pull #1003)
Initial draft of content for issue #259 to provide a guidance section on aria-level.
1 parent ecdb87a commit 4dcd209

File tree

1 file changed

+120
-1
lines changed

1 file changed

+120
-1
lines changed

‎aria-practices.html

+120-1
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ <h4>Principle 2: ARIA Can Both Cloak and Enhance, Creating Both Power and Danger
106106
<p>On the other hand, some uses of ARIA are more like suspenders or belts; they add meaning that provides essential support to the original content.</p>
107107
<pre><code>
108108
&lt;button aria-pressed=&quot;false&quot;&gt;Mute&lt;/button&gt;
109-
</code></pre>
109+
</code></pre>
110110
<p>
111111
This is the power of ARIA.
112112
It enables authors to describe nearly any user interface component in ways that assistive technologies can reliably interpret, thus making components accessible to assistive technology users.
@@ -6279,6 +6279,125 @@ <h3>Indicating sort order with <code>aria-sort</code></h3>
62796279

62806280
</section>
62816281

6282+
<section id="aria-level">
6283+
<h2>Describing Hierarchical Structure with <code>aria-level</code></h2>
6284+
<p>When elements have a hierarchical relationship, such as headers of sections or data in tree structures, <code>aria-level</code> is used to communicate the hierarchy between elements to assistive technologies. The value of <code>aria-level</code> is numeric, with <code>1</code> indicating the top level of the structure. The number increases for each level of nesting.</p>
6285+
<p>Do not use <code>aria-level</code> when the DOM structure already accurately represents the elements' hierarchical relationships.</p>
6286+
<p>The <code>aria-level</code> attribute can be used on the following roles:</p>
6287+
<ul>
6288+
<li><code>heading</code></li>
6289+
<li><code>listitem</code></li>
6290+
<li><code>row</code></li>
6291+
<li><code>tablist</code> (not recommended)</li>
6292+
<li><code>grid</code> (not recommended)</li>
6293+
</ul>
6294+
<section id="aria-level_heading_role">
6295+
<h3><code>heading</code> Role</h3>
6296+
<p>Used together, the <code>aria-level</code> attribute and <code>heading</code> role will be treated the same by assistive technologies as the native HTML header elements: <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code> and <code>h6</code>. Do not use attribute <code>aria-level</code> and <code>heading</code> when a native HTML element can be used.</p>
6297+
<p>This example uses the <code>heading</code> role and <code>aria-level</code> attribute to communicate levels of headings for a graph created with an SVG. The headings "Deciduous Trees" and "Evergreen Trees" are both subheadings to "Total Trees".</p>
6298+
<pre><code>&lt;svg width="1000" height="1000"&gt;
6299+
&lt;text x="10" y="10" role="header" aria-level="1"&gt;Total Trees:&lt;/text&gt;
6300+
&lt;text x="10" y="100" role="header" aria-level="2"&gt;Deciduous Trees:&lt;/text&gt;
6301+
&lt;text x="10" y="200" role="header" aria-level="2"&gt;Evergreen Trees:&lt;/text&gt;
6302+
...
6303+
&lt;/svg&gt;
6304+
</code></pre>
6305+
6306+
<section id="aria-level_heading_role_remediation">
6307+
<h4>Remediation Uses Cases</h4>
6308+
<p>In rare scenarios, legacy code cannot be converted to using HTML header elements. In these cases, the <code>aria-level</code> attribute and the <code>heading</code> role can be added to the website's header elements to communicate to assitive technologies that those elements should be treated like a native HTML section heading element.</p>
6309+
<p>For example, "Definition of a Room" is a subsection of "Housing Specification":</p>
6310+
<pre><code>&lt;div role="heading" aria-level="1" class="header-big"&gt;Housing Specification&lt;/div&gt;
6311+
&lt;div role="section" aria-labelledby="room-definition"&gt;
6312+
&lt;div role="heading" aria-level="2" id="room-definition" class="header-small"&gt;Definition of a Room&lt;/div&gt;
6313+
...
6314+
&lt;/div&gt;
6315+
</code></pre>
6316+
<p>Equivalent (and preferred) HTML:</p>
6317+
<pre><code>&lt;h1&gt;Housing Specification&lt;/h1&gt;
6318+
&lt;section aria-labelledby="room-definition"&gt;
6319+
&lt;h2 id="room-definition"&gt;Definition of a Room&lt;/h2&gt;
6320+
...
6321+
&lt;/section&gt;
6322+
</code></pre>
6323+
</section>
6324+
</section>
6325+
6326+
<section id="aria-level_listitem_role">
6327+
<h3><code>listitem</code> role</h3>
6328+
<p>The <code>aria-level</code> attribute can be used on elements with <code>listitem</code> role to represent list subitems when the structure of the DOM tree does not imply the intended level of nesting. For example, to quote a item in a nested to-do list, use the 'aria-level' attribute on the list items.</p>
6329+
<pre><code>&lt;blockquote&gt;
6330+
&lt;ul&gt;
6331+
&lt;li aria-level="2"&gt;Wash Dishes&lt;/li&gt;
6332+
&lt;/ul&gt;
6333+
&lt;/blockquote&gt;
6334+
&lt;p&gt;I can do this item, but I can't do the other clean up items.&lt;/p&gt;
6335+
</code></pre>
6336+
</section>
6337+
6338+
<section id="aria-level_treeitem_role">
6339+
<h3><code>treeitem</code> role</h3>
6340+
<p>The attribute <code>aria-level</code> can be used on elements with role <code>treeitem</code> to explicitly set the level of items within the <a href="#TreeView">Tree View Design Pattern</a>.</p>
6341+
<p>The computed <code>aria-level</code> of a <code>treeitem</code> within a tree is based on the number of 'group' role elements in the ancestor chain between the treeitem and the tree role, where the top level <code>treeitems</code> are <code>aria-level</code> 1. In the following example of a discussion board with nested replies, the top level post "What color should we paint the bike shed?" has an implicit <code>aria-level='1'</code>. The first reply has an implicit <code>aria-level='2'</code>, the response to that first reply has an implicit <code>aria-level='3'</code>.</p>
6342+
<pre><code>&lt;ul role='tree'&gt;
6343+
&lt;li role='treeitem'&gt;
6344+
What color should we paint the bike shed?
6345+
&lt;ul role='group'&gt;
6346+
&lt;li role='treeitem''&gt;
6347+
Green.
6348+
&lt;ul role='group'&gt;
6349+
&lt;li role='treeitem'&gt;
6350+
Green is boring, let's do purple.
6351+
&lt;/li&gt;
6352+
&lt;/ul&gt;
6353+
&lt;/li&gt;
6354+
&lt;/ul&gt;
6355+
&lt;/li&gt;
6356+
&lt;/ul&gt;
6357+
</code></pre>
6358+
<p>To override the <code>aria-level</code> calculated from the number of <code>group</code> role parents, set <code>aria-level</code> explicitly. Setting <code>aria-level</code> explictly might be necessary if only part of a tree is loaded and the implicity calculations cannot account for the missing part of the tree.</p>
6359+
<pre><code>&lt;ul role='tree'&gt;
6360+
&lt;li role='treeitem' aria-level='1'&gt;
6361+
What color should we paint the bike shed?
6362+
&lt;button&gt;Show 98 hidden replies&lt;/button&gt;
6363+
&lt;ul role='group'&gt;
6364+
&lt;li role='treeitem' aria-level='100'&gt;
6365+
I disagree with all 98 people who have replied before me, it should be rainbow colored.
6366+
&lt;/li&gt;
6367+
&lt;/ul&gt;
6368+
&lt;/li&gt;
6369+
&lt;/ul&gt;
6370+
</code></pre>
6371+
</section>
6372+
6373+
<section id="aria-level_row_role">
6374+
<h3><code>row</code> Role</h3>
6375+
<p>The <code>aria-level</code> attribute can be used on an element with <code>row</code> role to describe nesting of rows in a <code>treegrid</code>, as is explained in the <a href="#treegrid">treegrid pattern</a>. In this example, the DOM tree does not represent the hierarchical relationship between rows. Each email is in a <code>tr</code> element, which are siblings in the DOM tree, therefore <code>aria-level</code> is necessary to communicate that the emails form a tree structure.</p>
6376+
<pre><code>&lt;table role='treegrid'&gt;
6377+
&lt;tr&gt;
6378+
&lt;th&gt;From:&lt;/th&gt;
6379+
&lt;th&gt;Subject:&lt;/th&gt;
6380+
&lt;/tr&gt;
6381+
&lt;tr aria-level='1'&gt;
6382+
&lt;td&gt;Laura&lt;/td&gt;
6383+
&lt;td&gt;We should definitely cover the bike shed in rainbows.&lt;/td&gt;
6384+
&lt;/tr&gt;
6385+
&lt;tr aria-level='2'&gt;
6386+
&lt;td&gt;Fred&lt;/td&gt;
6387+
&lt;td&gt;Re: We should definitely cover the bike shed in rainbows.&lt;/td&gt;
6388+
&lt;/tr&gt;
6389+
&lt;/table&gt;
6390+
</code></pre>
6391+
<p>Do not use <code>aria-level</code> on rows that are in a <code>grid</code> or a <code>table</code> because only rows in a <code>treegrid</code> table are expected to have a hierarchical relationship.</p>
6392+
</section>
6393+
6394+
<section id="aria-level_grid_role">
6395+
<h3><code>grid</code> Role</h3>
6396+
<p>The attribute <code>aria-level</code> can be used on elements with role <code>grid</code> to represent nested grids but it is not recommended.</p>
6397+
</section>
6398+
6399+
</section>
6400+
62826401
<section id="presentation_role">
62836402
<h2>Intentionally Hiding Semantics with the <code>presentation</code> Role</h2>
62846403
<p>

0 commit comments

Comments
 (0)