amenui
en·中 github ↗ v0.0.1
01docs 02components 03lab 04works
en·中github ↗
×

docs / concepts / design / 1.14 the accessibility mirror docs / concepts / design /

1.14 The accessibility mirror

03.30

The picture is drawn into a canvas, invisible to screen readers. So the runtime builds a mirror from the interface tree (Ui::a11y() -> Vec<A11yNode>, no GPU, no platform): every element's key, its nearest ancestor in the mirror, role, name, state (value and range, text, checked, selected, heading level, expanded, description, live, invalid, required, modal, disabled, focusable) and where it is drawn.

Roles (el::Role, the WAI-ARIA roles of the same names) are written by components (El::role, El::label, El::checked, El::selected, El::value_range, El::text_value, El::heading, El::expanded, El::description, El::live, El::invalid, El::required): a button → button; a switch → switch (aria-checked); a slider → slider (aria-valuenow / min / max); tabs → tablist / tab (aria-selected); text fields and multi-line fields → textbox (the name is the placeholder, the value the text); a dialog's card → dialog (aria-modal, named by its title); lists and the ten thousand rows → list / listitem (aria-selected); a picture → img (named by its caption, "Picture" without one); the page title → heading 1, section headings → heading 2; an accordion header, a select and a popover's button → aria-expanded; a status line or toast → status, announced politely (aria-live) unless it says otherwise. Without a role: something pressable and focusable is a button; text not inside a control is text; a picture is img. Without a name, the text inside the element is used (the names of buttons, tabs, list items and switches are their own text), and that text does not appear again on its own. While a dialog is open, only what is inside it is in the mirror (the page beneath is inert to screen readers).

Syncing: Ui::a11y_diff() compares by key the way layout does: against what was last handed over, changed or new nodes give Set, missing ones Remove, and a focus change Focus. So one press of a button sends only the count line and the focus.

Web (web/amenui.js, and the website's web/page.html): a tree of <div>s in #a11y (nested as in the mirror), each with role and aria-* attributes, fixed at the position where it is drawn; the whole tree has opacity: 0 and ignores the pointer (present for screen readers, absent for eyes and the pointer). It is updated after every event and every frame by a11y_update() (a JSON diff). Focus in both directions: when a mirror element gets focus (the screen reader moves focus there), a11y_focus(key) gives that control the runtime's focus; when the runtime's focus changes, DOM focus follows only if it was already in the mirror (otherwise the canvas or the hidden input element keeps the keyboard). Activation: a click on a mirror element (a screen reader's "press") calls a11y_activate(key) → Ui::activate: the same message, front, commit and condensing as Enter. Keyboard events come from the window as usual, so with focus on the mirror's slider the arrow keys change it.

Native (app::access, AccessKit through accesskit_winit, so UI Automation on Windows, NSAccessibility on macOS and AT-SPI on Linux): the window is one Window node and every A11yNode an accesskit::Node under its mirrored parent (role, name, bounds in window px, value and range, text, toggled, selected, expanded, description, live, invalid, required, level, modal, disabled), with ids hashed from keys so they stay put across rebuilds. The tree is built only while assistive technology listens, after each drawn frame. Actions: Focus → focus_key, Click → activate, Increment / Decrement → focus and → / ←. The window is created hidden and shown once the adapter is attached, as AccessKit requires.

Acceptance: tests/a11y.rs: #button has a focusable button, a disabled button, the page title as a level 1 heading and the count as text, and the button's text doesn't appear on its own; the second a11y_diff is empty; activate sends the same message as a press and focuses it, and the diff after it holds only what changed; with #dialog open there is a modal dialog with everything else inside it, a close button and a text field, and the page beneath is absent; the slider's value is within its range, the switch has a checked state, each tab list has exactly one selected tab, the list has a selected item, the text field's value is its text, and the picture has a name; after a screen reader gives the switch focus, Space toggles it and activate toggles it back. app::access's unit test: the AccessKit tree has the window and every mirrored node, a status is polite, bounds are in window px, and Click reaches the runtime. Web (Playwright's ariaSnapshot()): #button's buttons, heading, count and disabled state; pressing the button through the accessibility tree makes the count 1; with #dialog open there is a dialog with aria-modal="true", the page title is absent, and the text field and buttons are present; #slider has a named slider with aria-valuenow / min / max; with focus on the mirror's slider, → takes the value from 40 to 41. No console errors.