Skip to content

[html-aam] Set heading level based on HTML computed heading level #2720

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.

Sign up for GitHub

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

Open
keithamus wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[html-aam] Set heading level based on HTML computed heading level #2720

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2e561d1
[html-aam] Set heading level based on HTML computed heading level
keithamus Aug 14, 2025
2cea8b4
Fix URLs
keithamus Jan 26, 2026
7d1ae7f
Change note to normative
keithamus Jun 12, 2026
c387902
Adjust link to point to heading level, not just offset
keithamus Jun 12, 2026
606f065
Add note around implicit capping
keithamus Jun 12, 2026
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
109 changes: 107 additions & 2 deletions html-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2666,8 +2666,12 @@ <h4 id="el-h1-h6">`h1`, `h2`, `h3`, `h4`, `h5`, and `h6`</h4>
<tr>
<th>[[wai-aria-1.2]]</th>
<td>
<a class="core-mapping" href="#role-map-heading">`heading`</a> role, with the <a class="core-mapping" href="#ariaLevel">`aria-level`</a> property set to the number in the element's tag
name.
<a class="core-mapping" href="#role-map-heading">`heading`</a> role, with the <a class="core-mapping" href="#ariaLevel">`aria-level`</a> property set to
<a data-cite="html/sections.html#get-an-element's-computed-heading-level">the computed heading level</a>; this is the number from the element's tag name (e.g., 2 for `h2`), adjusted
by any <a href="#att-headingoffset">`headingoffset`</a> or <a href="#att-headingreset">`headingreset`</a> attributes in scope.
<p>If an explicit <a class="core-mapping" href="#ariaLevel">`aria-level`</a> attribute is specified on the element, user agents MUST use that value instead of the implicit `aria-level` value derived from
the computed heading level.</p>
<p class="note">The <a data-cite="html/sections.html#get-an-element's-computed-heading-level">computed heading level algorithm</a> caps the implicit `aria-level` value at 9.</p>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -11154,6 +11158,107 @@ <h4 id="att-headers">`headers`</h4>
</tr>
</tbody>
</table>
<h4 id="att-headingoffset">`headingoffset`</h4>
<table class="data" aria-labelledby="att-headingoffset">
<tbody>
<tr>
<th>HTML Specification</th>
<td><a data-cite="html/sections.html#attr-headingoffset">`headingoffset`</a></td>
</tr>
<tr>
<th>Element(s)</th>
<td>
<a data-cite="html/infrastructure.html#html-elements">HTML elements</a>
</td>
</tr>
<tr>
<th>[[WAI-ARIA-1.2]]</th>
<td>Adjusts the <a class="core-mapping" href="#ariaLevel">`aria-level`</a> property of in-scope <a href="#el-h1-h6">heading elements</a> by the specified offset value.</td>
</tr>
<tr>
<th>
<a href="https://msdn.microsoft.com/en-us/library/dd373608%28v=VS.85%29.aspx">MSAA</a> + <a href="http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/">IAccessible2</a>
</th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th><a href="https://msdn.microsoft.com/en-us/library/ms726297%28v=VS.85%29.aspx">UIA</a></th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th><span class="informative">[[ATK]]</span></th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th><a href="https://developer.apple.com/reference/appkit/nsaccessibility">AX</a></th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th>Comments</th>
<td></td>
</tr>
</tbody>
</table>
<h4 id="att-headingreset">`headingreset`</h4>
<table class="data" aria-labelledby="att-headingreset">
<tbody>
<tr>
<th>HTML Specification</th>
<td><a data-cite="html/sections.html#attr-headingreset">`headingreset`</a></td>
</tr>
<tr>
<th>Element(s)</th>
<td>
<a data-cite="html/infrastructure.html#html-elements">HTML elements</a>
</td>
</tr>
<tr>
<th>[[WAI-ARIA-1.2]]</th>
<td>
Resets the <a class="core-mapping" href="#ariaLevel">`aria-level`</a> property of in-scope <a href="#el-h1-h6">heading elements</a> to the specified base level before applying any
offset.
</td>
</tr>
<tr>
<th>
<a href="https://msdn.microsoft.com/en-us/library/dd373608%28v=VS.85%29.aspx">MSAA</a> + <a href="http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/">IAccessible2</a>
</th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th><a href="https://msdn.microsoft.com/en-us/library/ms726297%28v=VS.85%29.aspx">UIA</a></th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th><span class="informative">[[ATK]]</span></th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th><a href="https://developer.apple.com/reference/appkit/nsaccessibility">AX</a></th>
<td>
<div class="general">Not mapped</div>
</td>
</tr>
<tr>
<th>Comments</th>
<td></td>
</tr>
</tbody>
</table>
<h4 id="att-height">`height`</h4>
<table class="data" aria-labelledby="att-height">
<tbody>
Expand Down