Skip to content

Editorial: fix normative statements #2590

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

Merged
merged 2 commits into from
Sep 2, 2025
Merged

Editorial: fix normative statements #2590

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a099aa
fix normative statements
jnurthen Aug 6, 2025
df7cd05
fix copy/paste error
jnurthen Aug 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
42 changes: 25 additions & 17 deletions html-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ <h2>Mapping HTML to Accessibility APIs</h2>
<h3>General Rules for Exposing WAI-ARIA Semantics</h3>
<p class="note">WAI-ARIA support was first introduced to HTML in [[HTML5]].</p>
<p>
Where an HTML element or attribute has default WAI-ARIA semantics, it MUST be exposed to the platform <a class="termref">accessibility APIs</a> in a way that conforms to
<a>User Agents</a> MUST expose HTML elements or attributes with default WAI-ARIA semantics to the platform <a class="termref">accessibility APIs</a> in a way that conforms to
<a class="core-mapping" href="#mapping_general">General rules for exposing WAI-ARIA semantics</a> in the [[[core-aam-1.2]]].
</p>
</section>
Expand Down Expand Up @@ -242,15 +242,15 @@ <h3 id="minimum-role">Exposing HTML Features That Require a Minimum Role</h3>
to a minimum role.
</p>
<p>
When these conditions are met, the browser MUST expose an object using the mappings defined in CORE-AAM for the specified minimum role. If the element has multiple attributes specified which
When these conditions are met, user agents MUST expose an object using the mappings defined in CORE-AAM for the specified minimum role. If the element has multiple attributes specified which
require a minimum role be returned as the computed role for the element, prioritize the more specific role in the ARIA taxonomy.
</p>
</section>
<section>
<h3>HTML Element Role Mappings</h3>
<ul>
<li>
HTML elements with implicit WAI-ARIA role semantics MUST be mapped to platform <a class="termref">accessibility APIs</a> according to the identified WAI-ARIA role mapping as defined in the
User agents MUST map HTML elements with implicit WAI-ARIA role semantics to platform <a class="termref">accessibility APIs</a> according to the identified WAI-ARIA role mapping as defined in the
[[core-aam-1.2]] specification.
</li>
<li>
Expand All @@ -276,7 +276,7 @@ <h4 id="platform-api-mapping-requirements">Platform API mapping requirements</h4
<ul>
<li>
When HTML elements do not have an exact or equivalent mapping to a valid, non-abstract <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> role, a unique `computedrole`
string has been specified to serve as the return value for interoperability testing purposes. For instance, the `video` element MAY be exposed with a `computedrole` of "`html-video`".
string has been specified to serve as the return value for interoperability testing purposes. For instance, user agents MAY expose the `video` element with a `computedrole` of "`html-video`".
Authors MUST NOT use any `html-`prefixed computed role string in the role attribute (such as `html-video`). User Agents MUST ignore any abstract or invalid role token.
<div class="example">
<code> &lt;video> &lt;!-- computedrole returns 'html-video' --> &lt;main role="html-video"> &lt;!-- Author error. computed role returns 'main' --> </code>
Expand All @@ -285,7 +285,7 @@ <h4 id="platform-api-mapping-requirements">Platform API mapping requirements</h4
<li>
<strong>IAccessible2:</strong>
<ul>
<li>All elements with accessible objects should implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.</li>
<li>All elements with accessible objects SHOULD implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.</li>
</ul>
</li>
<li>
Expand All @@ -306,7 +306,7 @@ <h4 id="platform-api-mapping-requirements">Platform API mapping requirements</h4
<li>
<strong>AXAPI:</strong>
<ul>
<li>User agents should return a user-presentable, localized string value for the Mac Accessibility AXRoleDescription.</li>
<li>User agents SHOULD return a user-presentable, localized string value for the Mac Accessibility AXRoleDescription.</li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -807,8 +807,12 @@ <h4 id="el-audio">`audio`</h4>
<a class="core-mapping" href="#role-map-button">`button`</a> or <a class="core-mapping" href="#role-map-slider">`slider`</a>).
</div>
<div class="general">
Text objects associated with loading or error messages, and any UI control not currently displayed, MAY be present in the <a class="termref">accessibility tree</a> and marked as
hidden or off-screen.
User agents MAY include the following in the <a class="termref">accessibility tree</a> and mark them as
hidden or off-screen:
<ul>
<li>Loading messages or error messages</li>
<li>UI controls that are not currently displayed</li>
</ul>
</div>
</td>
</tr>
Expand Down Expand Up @@ -2895,8 +2899,8 @@ <h4 id="el-hgroup">`hgroup`</h4>
<tr>
<th>Comments</th>
<td>
If an `hgroup` contains multiple heading elements, then the heading element with the highest priority level MAY be treated as the sole heading of the `hgroup`. All other heading
elements MAY instead be exposed as if they were <a href="#el-p">`p`</a> elements. See <a class="core-mapping" href="#role-map-paragraph">`paragraph` role on Core AAM</a>.
If an `hgroup` contains multiple heading elements, then the user agent MAY treat the heading element with the highest priority level as the sole heading of the `hgroup`. The user agent MAY expose all other heading
elements as if they were <a href="#el-p">`p`</a> elements. See <a class="core-mapping" href="#role-map-paragraph">`paragraph` role on Core AAM</a>.
</td>
</tr>
</tbody>
Expand Down Expand Up @@ -6841,7 +6845,7 @@ <h4 id="el-summary">`summary`</h4>
<tr>
<th>Comments</th>
<td>
If a `summary` element is not a child of a `details` element, or it is not the first `summary` element of a parent `details`, then the `summary` element MUST be exposed with a
If a `summary` element is not a child of a `details` element, or it is not the first `summary` element of a parent `details`, then user agents MUST expose the `summary` element with a
`generic` role.
</td>
</tr>
Expand Down Expand Up @@ -7929,8 +7933,12 @@ <h4 id="el-video">`video`</h4>
<a class="core-mapping" href="#role-map-button">`button`</a> or <a class="core-mapping" href="#role-map-slider">`slider`</a>).
</div>
<div class="general">
Text objects associated with loading or error messages, and any UI control not currently displayed, MAY be present in the <a class="termref">accessibility tree</a> and marked as
hidden or off-screen.
User agents MAY include the following in the <a class="termref">accessibility tree</a> and mark them as
hidden or off-screen:
<ul>
<li>Loading messages or error messages</li>
<li>UI controls that are not currently displayed</li>
</ul>
</div>
</td>
</tr>
Expand Down Expand Up @@ -8017,8 +8025,8 @@ <h4 id="el-wbr">`wbr`</h4>
<h3>HTML Attribute State and Property Mappings</h3>
<ul>
<li>
HTML attributes with default WAI-ARIA state and property semantics MUST be mapped to platform <a class="termref">accessibility APIs</a> according to those WAI-ARIA state and property
mappings as defined in the [[core-aam-1.2]] specification.
User agents MUST map HTML attributes with default WAI-ARIA state and property semantics to platform <a class="termref">accessibility APIs</a> according to the identified WAI-ARIA state and property mapping as defined in the
[[core-aam-1.2]] specification.
</li>
<li>A '?' in a cell indicates the data has yet to be provided.</li>
<li>
Expand Down Expand Up @@ -16516,7 +16524,7 @@ <h4>`summary` Element Accessible Name Computation</h4>
</li>
<li>Otherwise use `summary` element subtree.</li>
<li>Otherwise use `title` attribute.</li>
<li>If there is no `summary` element as a direct child of the `details` element, the user agent should provide one with a subtree containing a localized string of the word "details".</li>
<li>If there is no `summary` element as a direct child of the `details` element, the user agent SHOULD provide one with a subtree containing a localized string of the word "details".</li>
<li>
If there is a `summary` element as a direct child of the `details` element, but none of the above yield a usable text string, there is no
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.
Expand Down Expand Up @@ -16667,7 +16675,7 @@ <h4>Text-level Element Accessible Name Computation</h4>
<section id="accdesc-computation">
<h3>Accessible Description Computation</h3>
<p>
An <a data-cite="accname-1.2/#dfn-accessible-description">accessible description</a> MAY be provided to any HTML element that is a valid child of the `body` element. The following list
Authors MAY provide an <a data-cite="accname-1.2/#dfn-accessible-description">accessible description</a> for any HTML element that is a valid child of the `body` element. The following list
represents the order of precedence for <a class="termref">user agents</a> to compute the <a data-cite="accname-1.2/#dfn-accessible-description">accessible description</a> of an element. As
defined by <a data-cite="accname-1.2/#mapping_additional_nd_description">Accessible Name and Description Computation: Description Computation </a>, <a class="termref">user agents</a> MUST
use the first applicable description source, even if its use results in an empty description.
Expand Down