Skip to content

Update: change default role for custom elements #2383

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

Update: change default role for custom elements #2383

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
3fd715c
Update: change default role for custom elements
scottaohara Nov 22, 2024
2e4fe8f
fix typo / missing in-page link id
scottaohara Nov 22, 2024
0d94242
Update html-aam/index.html
scottaohara Nov 22, 2024
a40c5e0
Update html-aam/index.html
scottaohara Nov 22, 2024
34ceeb0
Update html-aam/index.html
scottaohara Nov 22, 2024
6f6ebf8
update per feedback/discussion about referenced elements
scottaohara Nov 22, 2024
ae672af
Update index.html
scottaohara Nov 22, 2024
2215edc
Update html-aam/index.html
scottaohara Nov 22, 2024
7ef3647
Update html-aam/index.html
scottaohara Nov 22, 2024
1c00754
or else if otherwise sure?
scottaohara Nov 22, 2024
2532049
combining things
scottaohara Nov 22, 2024
9a1e54a
add in no shadow root use cae
scottaohara Nov 27, 2024
620e070
Update html-aam/index.html
scottaohara Dec 17, 2024
e2c538d
Update html-aam/index.html
scottaohara Dec 17, 2024
499fe99
Update html-aam/index.html
scottaohara Feb 6, 2025
a4d84a8
Update html-aam/index.html
scottaohara Feb 6, 2025
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
80 changes: 24 additions & 56 deletions html-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,8 @@ <h3>HTML Element Role Mappings</h3>
specified which would require a more specific <a>minimum role</a> to be exposed.
</li>
<li>
Where an element is indicated as having &quot;No corresponding (WAI-ARIA) role&quot;, or is mapped to the <a class="core-mapping" href="#role-map-generic">`generic`</a> role, user agents
Where an element is mapped to the <a class="core-mapping" href="#role-map-generic">`generic`</a>
or <a class="core-mapping" href="#role-map-none">`none`</a> roles, user agents
MUST NOT expose the <a class="core-mapping" href="#ariaRoleDescription">`aria-roledescription`</a> property value in the <a class="termref">accessibility tree</a> unless the element has an
explicit, conforming `role` attribute value which [[WAI-ARIA-1.2]] does not prohibit the use of `aria-roledescription`.
</li>
Expand Down Expand Up @@ -840,18 +841,35 @@ <h4 id="el-audio">`audio`</h4>
</tr>
</tbody>
</table>
<h4 id="el-autonomous-custom-element">autonomous custom element</h4>
<table class="data" aria-labelledby="el-autonomous-custom-element">
<h4 id="el-autonomous-custom-element">
autonomous custom elements
and
<span id="el-form-associated-custom-element">form-associated custom elements</span>
</h4>
<table aria-labelledby="el-autonomous-custom-element">
<tbody>
<tr>
<th>HTML Specification</th>
<td>
<a data-cite="HTML">autonomous custom element</a>
and
<a data-cite="html/custom-elements.html#custom-elements-face-example">form-associated custom element</a>
</td>
</tr>
<tr>
<th>[[wai-aria-1.2]]</th>
<td>If the author assigned a conforming ARIA role using the `role` attribute, map to that role. Otherwise, the <a class="core-mapping" href="#role-map-generic">`generic`</a> role.</td>
<td>
<ul>
<li>If the author assigned a conforming role using the `role` attribute, or by the custom element's internals: map to the specified role.</li>
<li>else if the author assigned HTML attributes that result in a <a>minimum role</a>: map to the minimum role.</li>
<li>else if the custom element is focusable: map to the <a class="core-mapping" href="#role-map-group">`group`</a> role</li>
Copy link

@jcsteh jcsteh Aug 29, 2025

Choose a reason for hiding this comment

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

Should this be done even if a custom element's ShadowRoot has delegatesFocus: true? It's a tricky one. On one hand, it's a pretty important principle to expose focusable elements to accessibility. On the other hand, when delegatesFocus is true, the element isn't in the tab order; it is effectively transparent as far as focus is concerned.

I think it's probably safer to still use role="group" even for delegatesFocus: true. For example, browser native date/time inputs expose the container and allow it to be focused, even though it isn't part of the tab order. Nevertheless, I thought I'd clarify because I haven't seen any discussion of delegatesFocus either here or in #2303.

<li>else if an author specifies a global ARIA attribute on the custom element that creates a relation with another element: map to the <a class="core-mapping" href="#role-map-group">`group`</a> role</li>
<li>else if the custom element has no attached shadow root: map to the <a class="core-mapping" href="#role-map-generic">`generic`</a> role</li>
<li>else if the custom element has an `aria-live` attribute: map to the <a class="core-mapping" href="#role-map-generic">`generic`</a> role</li>
<li>else if element internals are used to set a global ARIA property: map to the <a class="core-mapping" href="#role-map-generic">`generic`</a> role.</li>
<li>Otherwise, the custom element maps to the <a class="core-mapping" href="#role-map-none">`none`</a> role.</li>
</ul>
</td>
</tr>
<tr>
<th><a data-cite="core-aam-1.2/#roleMappingComputedRole">Computed Role</a></th>
Expand Down Expand Up @@ -2597,56 +2615,6 @@ <h4 id="el-form">`form`</h4>
</tr>
</tbody>
</table>
<h4 id="el-form-associated-custom-element">form-associated custom element</h4>
<table class="data" aria-labelledby="el-form-associated-custom-element">
<tbody>
<tr>
<th>HTML Specification</th>
<td>
<a data-cite="html/custom-elements.html#custom-elements-face-example">form-associated custom element</a>
</td>
</tr>
<tr>
<th>[[wai-aria-1.2]]</th>
<td>If the author assigned a conforming ARIA role using the `role` attribute, map to that role. Otherwise, the <a class="core-mapping" href="#role-map-generic">`generic`</a> role.</td>
</tr>
<tr>
<th><a data-cite="core-aam-1.2/#roleMappingComputedRole">Computed Role</a></th>
<td class="role-computed"><div class="general">Use WAI-ARIA mapping</div></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">Use WAI-ARIA mapping</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">Use WAI-ARIA mapping</div>
</td>
</tr>
<tr>
<th><span class="informative">[[ATK]]</span></th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
</td>
</tr>
<tr>
<th><a href="https://developer.apple.com/reference/appkit/nsaccessibility">AX</a></th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
</td>
</tr>
<!-- <th><a href="#accessible-name-and-description-computation">Naming Algorithm</a></th> -->
<tr>
<th>Comments</th>
<td></td>
</tr>
</tbody>
</table>
<h4 id="el-h1-h6">`h1`, `h2`, `h3`, `h4`, `h5`, and `h6`</h4>
<table class="data" aria-labelledby="el-h1-h6">
<tbody>
Expand Down Expand Up @@ -8786,7 +8754,7 @@ <h4 id="att-autofocus">`autofocus`</h4>
</tr>
<tr>
<th>Comments</th>
<td>Provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.</td>
<td>Provides a <a>minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.</td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -10475,7 +10443,7 @@ <h4 id="att-draggable">`draggable`</h4>
</tr>
<tr>
<th>Comments</th>
<td>Provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.</td>
<td>Provides a <a>minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.</td>
</tr>
</tbody>
</table>
Expand Down