Accessibility basics¶
NativeHTMLKit builds a native accessibility tree from your HTML (AccessKit, exposed through AT-SPI on Linux and UI Automation on Windows). Screen readers see roles, names and states derived from your markup, so ordinary semantic HTML is the most important tool.
Checklist¶
- Use real elements.
<button>for actions,<a href>for links,<input>/<select>/<textarea>for input, headings in order, lists for lists,<table>with<th>for tables. A<div>with a click handler is neither focusable nor announced as a button. - Name every control. Use
<label for="id">(or wrap the control in<label>); addaria-labelonly where no visible label exists, such as a search field. - Announce status changes. Put status text in an element with
role="status"(polite) orrole="alert"(important), and update it withset_text. - Keep keyboard paths. Everything must work with Tab, Shift+Tab, Enter and Space. Forms submit with Enter; modal
<dialog>s close with Escape. Move focus deliberately after actions (document.focus(id),Set-NativeHTMLKitFocus), as the todo tutorial does after adding an item. - Do not rely on colour alone. Pair colour with text or icons (for example, show a service state as text inside a coloured pill).
- Respect preferences. Style for
prefers-color-schemeandprefers-reduced-motion; Style with the supported CSS shows how. - Give images text. Every
<img>, including live bitmaps, needs a meaningfulalt; keep values you draw in a chart available as HTML text too (Live bitmap charts).
Check what assistive technology sees¶
The get_accessibility_tree document operation returns the tree the host exposes (roles, names, states, relations, bounds). Read it to confirm, for example, that the fields of a sign-up form are named "E-mail" and "Repeat password":
tree = doc.command("get_accessibility_tree")["tree"]
names = [(node["role"], node["name"]) for node in tree["nodes"] if node["name"]]
PowerShell: Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation get_accessibility_tree.
This is a quick structural check, not a substitute for testing with a screen reader (Orca on Linux, Narrator or NVDA on Windows).
Known limitations¶
Screen-reader coverage is still being qualified. Core 1.0.3 has a reported Orca issue with collapsed <select> announcements on Linux; see limitations.