Skip to content

Add namefrom: heading. #2650

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
cookiecrook wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Add namefrom: heading. #2650

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
17750f7
Add namefrom:heading again; Will year 6 be the year?
cookiecrook Oct 9, 2025
d0e22a5
backing out the region and form role changes based circumstances outl…
cookiecrook Oct 13, 2025
b19f0b9
m. hyphenation
cookiecrook Oct 20, 2025
47ef934
m. article typo based on the prior change from IDDFS to DFS.
cookiecrook Oct 20, 2025
0fcaeec
html aam updates for name from heading
scottaohara Oct 21, 2025
30a7f56
Apply suggestion from @jcsteh
scottaohara Oct 22, 2025
ac2b567
Merge branch 'main' into namefrom-heading-2025
daniel-montalvo Dec 9, 2025
72c1c15
Merge branch 'main' into namefrom-heading-2025
daniel-montalvo Dec 18, 2025
92fe150
Merge branch 'main' into namefrom-heading-2025
daniel-montalvo Jan 21, 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
4 changes: 4 additions & 0 deletions accname/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -646,6 +646,10 @@ <h4>Computation steps</h4>
</p>
</div>
</li>
<li id="comp_name_from_heading">
<em>Name From Heading:</em> Otherwise, if the <code>current node</code> has a role that supports <a class="specref" href="#namefromheading">nameFrom: heading</a>,
return the text alternative of the first descendant <a>element</a> node matching the role of <code>heading</code> in a <em>depth-first search.</em>
</li>
<li id="comp_name_from_content">
<span id="step2F"><!-- Don't link to this legacy numbered ID. --></span><em>Name From Content:</em> Otherwise, if the <code>current node's</code> <a class="termref">role</a> allows
<a class="specref" href="#namefromcontent">name from content</a>, or if the <code>current node</code> is referenced by <code>aria-labelledby</code>, <code>aria-describedby</code>, or
Expand Down
38 changes: 37 additions & 1 deletion html-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16816,7 +16816,43 @@ <h4>`iframe` Element Accessible Name Computation</h4>
</p>
</section>
<section>
<h4>Section and Grouping Element Accessible Name Computation</h4>
<h4>`dialog` Element Accessible Name Computation</h4>
Comment thread
jcsteh marked this conversation as resolved.
<ol>
<li>
If the `dialog` element has an <a data-cite="wai-aria-1.2/#aria-label">`aria-label`</a> or an <a data-cite="wai-aria-1.2/#aria-labelledby">`aria-labelledby`</a>
attribute the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is to be calculated using the algorithm defined in
<a class="accname">Accessible Name and Description: Computation and API Mappings</a>.
</li>
<li>
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty, then: if the `dialog` element has a
<a href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</a> element with a role of `heading`, then use the
<a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of the element as defined in
<a data-cite="accname-1.2/#comp_name_from_heading">accname: Name from Heading</a>.
</li>
<li>Otherwise, use the `title` attribute.</li>
<li>If none of the above yield a usable text string there is no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.</li>
</ol>
</section>
<section>
<h4>`article` Element Accessible Name Computation</h4>
<ol>
<li>
If the `article` element has an <a data-cite="wai-aria-1.2/#aria-label">`aria-label`</a> or an <a data-cite="wai-aria-1.2/#aria-labelledby">`aria-labelledby`</a>
attribute the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is to be calculated using the algorithm defined in
<a class="accname">Accessible Name and Description: Computation and API Mappings</a>.
</li>
<li>
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty, then: if the `dialog` element has a
Comment thread
scottaohara marked this conversation as resolved.
Outdated
<a href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</a> element with a role of `heading`, then use the

@jcsteh jcsteh Oct 22, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This refers explicitly to a DOM descendant. Does this mean aria-owns content should explicitly be excluded from this check? For example, should we skip NameFrom: heading in this case?

data:text/html,<article aria-owns="content"></article><div id="content"><h1>Some heading</h1>

Does that also mean we shouldn't consider aria-owns content when doing name computation for a dialog? For example, in this case, do we take first or second as the label of the dialog?

data:text/html,<article aria-owns="first second"><h1 id="second">second</h1></article><h1 id="first">first</h1>

I think we should respect aria-owns for consistency. That means we should be using accessibility descendants.

<a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of the element as defined in
<a data-cite="accname-1.2/#comp_name_from_heading">accname: Name from Heading</a>.
</li>
<li>Otherwise, use the `title` attribute.</li>
Comment thread
rahimabdi marked this conversation as resolved.
<li>If none of the above yield a usable text string there is no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.</li>
</ol>
</section>
<section>
<h4>Other Section and Grouping Element Accessible Name Computation</h4>
<ol>
<li>
If the element has an <a data-cite="wai-aria-1.2/#aria-label">`aria-label`</a> or an <a data-cite="wai-aria-1.2/#aria-labelledby">`aria-labelledby`</a> attribute the
Expand Down
39 changes: 33 additions & 6 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1265,15 +1265,27 @@ <h3>Name From</h3>
having the lowest precedence for specifying a text alternative.
</li>
<li>
contents: name comes from the text value of the <a>element</a> node. Although this might be allowed in addition to "author" in some <a>roles</a>, this is used in content only if higher
priority "author" features are not provided. Priority is defined by the <cite><a href="" class="accname">Accessible Name and Description Computation</a></cite> [[ACCNAME-1.2]].
heading: name comes from the text alternative of the first descendant <a>element</a> node (depth-first search) matching the role of <code>heading</code> as defined in the AccName
computation algorithm for nameFrom: heading. Although "namefrom: heading" is allowed in addition to "namefrom: author" in some <a>roles</a>, "namefrom: heading" is used in content only
if higher priority "namefrom: author" features are not provided. Priority is defined by the <cite><a href="" class="accname">Accessible Name and Description Computation</a></cite>
[[ACCNAME-1.2]].
</li>
<li>
contents: name comes from the text value of the <a>element</a> node. Although this might be allowed in addition to "namefrom: author" or "namefrom:heading" in some <a>roles</a>, this
is used in content only if higher priority "namefrom: author" or "namefrom: heading" features are not provided. Priority is defined by the <cite><a href="" class="accname">Accessible
Name and Description Computation</a></cite> [[ACCNAME-1.2]].
</li>
<li>Priority is defined by the <cite><a href="" class="accname">Accessible Name and Description Computation</a></cite> [[ACCNAME-1.2]].</li>
<li>prohibited: the element does not support name from author. Authors MUST NOT use the <pref>aria-label</pref> or <pref>aria-labelledby</pref> attributes to name the element.</li>
</ol>
<section id="namefromauthor">
<h4>Roles Supporting Name from Author</h4>
<div id="index_fromauthor"></div>
</section>
<section id="namefromheading">
<h4>Roles Supporting Name from Heading</h4>
<div id="index_fromheading"></div>
</section>
<section id="namefromcontent">
<h4>Roles Supporting Name from Content</h4>
<div id="index_fromcontent"></div>
Expand Down Expand Up @@ -1670,7 +1682,12 @@ <h2>Definition of Roles</h2>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>

@cookiecrook cookiecrook Oct 13, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Reviewer context: this is on the alertdialog role

<td class="role-namefrom">
<ul>
<li>author</li>
<li>heading</li>
</ul>
</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
Expand Down Expand Up @@ -1886,7 +1903,12 @@ <h2>Definition of Roles</h2>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>

@cookiecrook cookiecrook Oct 13, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Reviewer context: this is on the article role

<td class="role-namefrom">
<ul>
<li>author</li>
<li>heading</li>
</ul>
</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
Expand Down Expand Up @@ -3631,7 +3653,7 @@ <h2>Definition of Roles</h2>
focus to dialogs. See the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/">WAI-ARIA Authoring Practices: Dialog (modal) pattern</a> for additional details on implementing
modal dialog design patterns.
</p>
<p>Authors SHOULD provide an accessible name for a dialog, which can be done with the <pref>aria-label</pref> or <pref>aria-labelledby</pref> attribute.</p>
<p>Authors SHOULD provide an accessible name for a dialog, using either <a href="#namecalculation">namefrom</a>: author or <a href="#namecalculation">namefrom</a>: heading.</p>

@rahimabdi rahimabdi Oct 15, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Given a dialog that contains an <h2> for example, would it be preferable for authors to use aria-labelledby or rely on nameFrom: heading? Should nameFrom: author be preferred over nameFrom: heading?

@cookiecrook cookiecrook Oct 20, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes, the AccName computation prioritizes namefrom:author first... namefrom:heading is only used as a fallback.

@cookiecrook cookiecrook Oct 20, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The direct author reference is probably slightly more performant, but I don't think a change is needed here unless you have one to suggest.

@rahimabdi rahimabdi Oct 21, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Just a personal clarification to make sure I'm using this new nameFrom technique properly 😄

<p>
Authors SHOULD ensure that all dialogs (both modal and non-modal) have at least one <a>focusable</a> descendant element. Authors SHOULD focus an element in the modal dialog when it is
displayed, and authors SHOULD constrain keyboard focus to focusable elements within a modal dialog, until dismissed.
Expand Down Expand Up @@ -3721,7 +3743,12 @@ <h2>Definition of Roles</h2>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>

@cookiecrook cookiecrook Oct 13, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Reviewer context: this is on the dialog role

<td class="role-namefrom">
<ul>
<li>author</li>
<li>heading</li>
</ul>
</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
Expand Down
Loading