screen-reader
Screen reader compatibility, Accessibility Tree hierarchy, Accessible Name Computation (AccName 1.2), ARIA live regions, roles/states/values, and cross-platform AT support (NVDA, VoiceOver, AccessKit).
- License 许可
- MIT
- 所属仓库
- poppyTM/oride
- 最近更新
- 2026-09-30
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- screen-reader
- description
- Screen reader compatibility, Accessibility Tree hierarchy, Accessible Name Computation (AccName 1.2), ARIA live regions, roles/states/values, and cross-platform AT support (NVDA, VoiceOver, AccessKit).
02 资源文件 5
- 参考文档checks/screen-reader-checklist.md1.1 KB
- 参考文档manifest.json1.8 KB
- 参考文档references/screen-reader-guide.md1.9 KB
- 脚本scripts/verify.sh1.7 KB
- 参考文档templates/screen-reader-report.md1.3 KB
03 SKILL.md 正文
Screen Reader Compatibility & Accessibility Tree Architecture
1. Title and Description
Screen Reader Compatibility & Accessibility Tree Architecture (screen-reader)
Governs the construction, inspection, and verification of the Accessibility Tree across Web applications, Desktop native software (AccessKit / AT-SPI / Windows UI Automation / macOS NSAccessibility), and mobile platforms. Enforces Accessible Name Computation (AccName 1.2), ARIA live region announcements, and accurate role/state/value contracts.
2. Purpose
Ensure blind, low-vision, and assistive technology users experience 100% semantic fidelity, receiving clear, context-rich auditory announcements for all UI states, dynamic updates, and interactive controls without visual dependence.
3. Prerequisites
- UI markup or view code (HTML/JSX/Svelte/Vue, Rust egui WidgetInfo, or Slint accessibility properties).
- Familiarity with the W3C WAI Accessible Name and Description Computation (AccName 1.2).
4. Inputs
- Component source files, dynamic data feeds, modal dialogs, and notifications.
- Target platform: Web (DOM Accessibility Tree) or Native Desktop (AccessKit / OS accessibility APIs).
5. Outputs
- Semantically sound markup and component properties exposing complete accessible names and roles.
- Dynamic announcement regions using
aria-livewith appropriate assertiveness. - Accessibility audit report conforming to
templates/screen-reader-report.md.
6. Execution Steps
Step 1: The Accessibility Tree Foundation
Assistive technologies (screen readers like NVDA, JAWS, VoiceOver, Orca) do not parse raw pixels or CSS styles. They consume the Accessibility Tree generated by the browser or OS: Every node in the Accessibility Tree must expose four fundamental properties:
- Role: What the element is (
button,dialog,heading,navigation,tab). - Name: The primary label announced when focused (
"Save Project","Close"). - State: Current condition (
aria-expanded="false",aria-checked="true",aria-disabled="false"). - Value: For range controls (
aria-valuenow="75",aria-valuemin="0",aria-valuemax="100").
Step 2: Accessible Name Computation (AccName 1.2)
Ensure every interactive control has a non-empty, unambiguous accessible name. The precedence order is:
aria-labelledby="id": Points to visible on-screen text elements. Highest priority.aria-label="text": Provides an explicit invisible label for icon buttons (<button aria-label="Delete file">🗑️</button>).- Native Label Elements: Visible
<label for="input-id">for form fields. - Subtree Text Content: Text inside
<button>Click Here</button>. - Fallbacks:
titleorplaceholder(Lowest priority; never rely solely on placeholders for accessible names!).
Step 3: Dynamic Updates with ARIA Live Regions
When content changes asynchronously without a page reload, notify screen reader users via aria-live:
aria-live="polite":- Screen reader waits until the user finishes typing or listening to current speech before speaking.
- Use for: Toast notifications, search result count updates (
"14 items found"), cart item counts.
aria-live="assertive":- Immediately interrupts current speech output.
- Restricted: Use exclusively for time-sensitive, safety-critical alerts (e.g. system disconnect, security error, session expiration countdown).
aria-atomic="true":- Tells the screen reader to announce the entire contents of the region when any part changes, rather than speaking only the fragmented diff.
Step 4: Semantic HTML Over ARIA Emulation
- First Rule of ARIA: If you can use a native HTML element or attribute with the semantics and behavior you require already built in, do so instead of re-purposing an element and adding an ARIA role, state, or property.
- Prefer
<button>over<div role="button">. - Prefer
<dialog>over<div role="dialog">. - Prefer
<h1>–<h6>over<div class="heading">. - Avoid redundant ARIA markup (
<button role="button">or<nav role="navigation">).
Step 5: Native Desktop Accessibility (AccessKit / egui / Slint)
For native desktop software built with immediate-mode GUI toolkits (like the Prumo Workspace Viewer):
- Register accessibility nodes using AccessKit:
- Assign
accesskit::Role::Button,accesskit::Role::TextInput, etc. - Set
node.set_label("Open File"). - Update
node.set_numeric_value_step(1.0)on sliders.
- Assign
- Verify that OS assistive technologies (VoiceOver on macOS, Windows Narrator / NVDA, AT-SPI Orca on Linux) receive focus events and announce controls accurately.
7. Verification
# 1. Automated accessibility tree audit using axe-core
npx axe-core-cli http://localhost:3000
# 2. Verify icon buttons have non-empty aria-label
./scripts/verify.sh .
8. Fallbacks & Failure Recovery
| Failure Class | Root Cause | Deterministic Remediation |
|---|---|---|
| Empty Accessible Name | Icon-only button (<button><svg/></button>) |
Add aria-label="Action description" to button, and mark the SVG aria-hidden="true". |
| Unannounced Form Error | Error message rendered dynamically below input | Add aria-describedby="error-id" to the input and place role="alert" on the error text container. |
| Chatty Live Region Loops | Live region continuously re-announces on every render | Mount the aria-live container empty on page load, and only populate its text content when a real update event occurs. |
9. Constraints
- Zero unnamed buttons: Every
<button>must have visible text or anaria-label. - Zero non-standard roles: Only use official W3C ARIA 1.2 roles; never invent custom roles (
role="tab-button"is invalid). - No silent state mutations: Toggling UI states without updating corresponding ARIA states (
aria-expanded,aria-checked) is rejected.
10. Examples
Anti-Pattern: Unnamed Icon Button & Unannounced Error
<!-- BAD: Screen reader announces 'button', zero context, error is invisible to AT -->
<button onclick="deleteItem()">
<svg class="trash-icon"></svg>
</button>
<div id="error-msg" class="text-red-500">Failed to save data.</div>
Idiomatic Pattern: Fully Accessible Component with Live Region
<!-- GOOD: Explicit accessible name, SVG hidden, input linked to label & error via ID -->
<button type="button" aria-label="Delete project from workspace" onclick="deleteItem()">
<svg class="trash-icon" aria-hidden="true" focusable="false"></svg>
</button>
<div class="form-field">
<label for="username-input">Username</label>
<input
type="text"
id="username-input"
name="username"
aria-required="true"
aria-invalid="true"
aria-describedby="username-error"
/>
<div id="username-error" role="alert" class="text-red-600 text-sm">
Username must be at least 3 characters long.
</div>
</div>
<!-- Dynamic toast announcement container -->
<div aria-live="polite" aria-atomic="true" class="sr-only" id="global-announcer">
<!-- JavaScript populates text here when asynchronous tasks finish -->
</div>
04 同仓库更多 Skills
zoom-reflow
暂无简介
wireframe-styleguide
暂无简介
visual-regression
Pixel-by-pixel snapshot testing, Playwright integration, dynamic content masking, deterministic font rendering, and cross-browser CI gates
ui-implementation
Component-driven UI implementation, multi-state matrix (default, hover, focus-visible, active, disabled, loading, empty, error), DTCG design tokens, responsive layout contracts, and accessibility tree mapping.
tui-editor-engine
Text buffer and editing semantics for a terminal code editor — index conversion, transaction-first editing, multi-cursor invariants, undo grouping, and large-file behaviour.
tree-sitter-context-indexing
暂无简介