Skip to content

Implement AT guidance system for issue #1942 #2597

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Implement AT guidance system for issue #1942 #2597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
43 changes: 43 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,49 @@ The ARIA repositories share a common set of resources to reduce redundancy. Shar

Todo: special characteristics table classes etc. used by the script

### Assistive Technology Implementation Guidance

The ARIA specification includes optional Assistive Technology (AT) guidance sections for roles, states, and properties that require implementation guidance beyond the normative accessibility API mappings. These sections provide implementation recommendations specifically for assistive technology developers.

#### When to Add AT Guidance

AT guidance should be added when:

1. **Complex user interaction patterns** - When a role or state involves multi-step interactions or complex navigation patterns
2. **Implementation variations** - When different assistive technologies might reasonably implement features differently
3. **User experience considerations** - When specific UX patterns would benefit users with disabilities
4. **Platform-specific behavior** - When behavior should differ across platforms (desktop, mobile, web)
5. **Common implementation mistakes** - When implementers frequently make specific errors that impact usability

#### Structure and Content Requirements

AT guidance sections should:

1. **Use proper heading hierarchy** - Main section header should be `<h5>`, subsections should be `<h6>`
2. **Follow RFC 2119 keywords** - Use MUST, SHOULD, MAY appropriately for normative guidance
3. **Be platform-specific when needed** - Separate subsections for different platforms or AT types
4. **Include concrete examples** - Provide specific implementation examples where helpful
5. **Focus on user benefit** - Explain how the guidance improves the user experience

#### Implementation

Add AT guidance sections using the following structure:

```html
<section class="at-guidance">
<h5>Assistive Technology Guidance</h5>
<p>General guidance that applies to all assistive technologies...</p>

<h6>Screen Reader Implementation</h6>
<p>Specific guidance for screen reader implementation...</p>

<h6>Voice Control Implementation</h6>
<p>Specific guidance for voice control software...</p>
</section>
```

The `.at-guidance` class provides visual styling to distinguish these sections in the rendered specification. The content should be placed immediately after the role/state/property definition but before any examples or related sections.

### Editors' Drafts

Official editors' drafts are published to [https://w3c.github.io/<shortName>/], where `shortName` is the value of `respecConfig.shortName` for each of the specs. This URIs are suitable for public references. Documents published to those locations are *static* snapshots from the Respec processor. This is to minimize load time for consumers of these drafts. Editors' drafts are automatically updated (if there are no errors) by GitHub actions run when commits are pushed to the main branch.
Expand Down
116 changes: 116 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,33 @@
xref: ["dom", "accname-1.2", "core-aam-1.2", "infra", "HTML"],
definitionMap: [],
};
</script>
<style>
/* AT Guidance Styling */
.at-guidance {
background-color: #f0f4ff;
border-left: 4px solid #0066cc;
padding: 1em;
margin: 1em 0;
border-radius: 4px;
}

.at-guidance h4 {
color: #0066cc;
margin-top: 0;
font-size: 1.1em;
}

.at-guidance-content {
font-style: italic;
}

.at-guidance::before {
content: "💡 ";
font-style: normal;
}
</style>
<script class="remove">
function respecChangelogFilter(commit) {
// if (commit.message.toLowerCase().startsWith("generated by")) return false;
// else if (commit.message.toLowerCase().startsWith("travis-ci")) return false;
Expand Down Expand Up @@ -9412,6 +9439,37 @@ <h5>Presentational Role Inheritance</h5>
</tr>
</tbody>
</table>

<div class="at-guidance">
<h5>Assistive Technology Guidance for <code>slider</code></h5>

<h6>Screen Readers</h6>
<p>When encountering a <code>slider</code>, screen readers <strong>MUST</strong> announce the role, accessible name, current value, and range when possible. The announcement <strong>SHOULD</strong> include:</p>
<ul>
<li>The accessible name of the slider</li>
<li>The role ("slider")</li>
<li>The current value (<code>aria-valuenow</code>)</li>
<li>The minimum and maximum values when available (<code>aria-valuemin</code> and <code>aria-valuemax</code>)</li>
<li>The orientation when explicitly set to "vertical"</li>
</ul>
<p>Screen readers <strong>SHOULD</strong> announce value changes as users interact with the slider using arrow keys or other input methods.</p>

<h6>Voice Control Software</h6>
<p>Voice control software <strong>SHOULD</strong> support commands to:</p>
<ul>
<li>Focus on the slider by name ("click brightness slider")</li>
<li>Increment or decrement values ("increase volume", "decrease brightness")</li>
<li>Set specific values when possible ("set volume to 50")</li>
</ul>

<h6>Switch Navigation</h6>
<p>Switch navigation software <strong>MUST</strong> ensure sliders are reachable in the focus order and <strong>SHOULD</strong> provide alternative interaction methods for users who cannot use arrow keys, such as:</p>
<ul>
<li>Increment/decrement buttons or commands</li>
<li>Text input for direct value entry</li>
<li>Alternative key mappings for adjustment</li>
</ul>
</div>
</div>
<div class="role" id="spinbutton">
<rdef>spinbutton</rdef>
Expand Down Expand Up @@ -9928,6 +9986,32 @@ <h5>Presentational Role Inheritance</h5>
removed, child <rref>insertion</rref> and <rref>deletion</rref> elements can either be retained to document the revision or replaced with the revised content.
</p>
</div>

<section class="at-guidance">
<h5>Assistive Technology Guidance</h5>
<div class="at-guidance-content">
<p><strong>Screen readers</strong> SHOULD provide users with clear indication when encountering suggestion content, such as announcing "suggestion" before reading the content changes.</p>

<p>Screen readers SHOULD offer navigation commands to move between suggestions within a document, such as a "next suggestion" keystroke.</p>

<p>When reading suggestion content, screen readers SHOULD:</p>
<ul>
<li>Clearly differentiate between deleted and inserted text, for example by saying "deleted: cat, inserted: dog"</li>
<li>Provide context about the suggestion when requested, such as accessing associated <code>aria-details</code> for author information or timestamps</li>
<li>Allow users to review suggestions at different verbosity levels (brief announcement vs. detailed information)</li>
</ul>

<p>Screen readers MAY provide specialized suggestion review modes that allow users to:</p>
<ul>
<li>Accept or reject suggestions if the application supports such interactions</li>
<li>Navigate to related comments or metadata referenced by <code>aria-details</code></li>
<li>Hear suggestions in context or extract them for separate review</li>
</ul>

<p><strong>Other assistive technologies</strong> SHOULD expose suggestion semantics through their respective accessibility APIs to enable users to understand the nature of content changes, even if specific suggestion-handling features are not implemented.</p>
</div>
</section>

<table class="def">
<caption>
Characteristics:
Expand Down Expand Up @@ -13795,6 +13879,38 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
</tr>
</tbody>
</table>

<div class="at-guidance">
<h5>Assistive Technology Guidance for <code>aria-expanded</code></h5>

<h6>Screen Readers</h6>
<p>When a user navigates to an element with <code>aria-expanded</code>, screen readers <strong>MUST</strong> announce the current expansion state. The announcement <strong>SHOULD</strong> include:</p>
<ul>
<li>The accessible name of the element</li>
<li>The role of the element (e.g., "button", "treeitem")</li>
<li>The expansion state: "expanded" when <code>aria-expanded="true"</code>, "collapsed" when <code>aria-expanded="false"</code></li>
<li>Information about the controlled content when <code>aria-controls</code> is present</li>
</ul>
<p>When the expansion state changes, screen readers <strong>MUST</strong> announce the new state. For tree items, screen readers <strong>SHOULD</strong> also announce when child items become available or unavailable.</p>

<h6>Voice Control Software</h6>
<p>Voice control software <strong>SHOULD</strong> support commands to:</p>
<ul>
<li>Expand collapsed elements ("expand menu", "open categories")</li>
<li>Collapse expanded elements ("collapse section", "close details")</li>
<li>Toggle expansion state ("toggle navigation")</li>
</ul>
<p>Commands <strong>SHOULD</strong> work with both the accessible name and the type of control.</p>

<h6>Switch Navigation</h6>
<p>Switch navigation software <strong>MUST</strong> provide clear indication of:</p>
<ul>
<li>Which elements can be expanded or collapsed</li>
<li>The current expansion state of each element</li>
<li>How to activate the expansion toggle</li>
</ul>
<p>For tree structures, switch navigation <strong>SHOULD</strong> provide efficient methods to navigate between parent and child items without requiring expansion state changes.</p>
</div>
</div>
<div class="property" id="aria-flowto">
<pdef>aria-flowto</pdef>
Expand Down
Loading