#Accessibility
What Krate Native guarantees screen readers and keyboard users on Linux, macOS and Windows, and what authors must do for title bars, menus and dialogs.
Experimental. Part of Krate Native. The Linux checks run as GUI tests through AT-SPI, the same bus Orca reads. On macOS the tests ask our own AppKit objects through NSAccessibility, and read the AX tree when the test process is allowed to; on Windows they read the UI Automation tree. The macOS and Windows tests run only in the CI native job: nothing here has been tried with VoiceOver or Narrator by hand, and no screen reader was used on any platform. The compatibility row
native-accessibilitysays the same, per platform.
A Krate Native window has two kinds of content. The page inside the webview is exposed by the engine (WebKitGTK, WKWebView, WebView2) from your HTML, so semantic markup, labels and ARIA are your job, exactly as on the web. Everything around the page is drawn or configured by the shell: window titles, menus, dialogs, the tray, notifications, split-pane dividers and the caption buttons. This page is about that second kind.
#What Krate guarantees
| Linux (AT-SPI) | macOS (NSAccessibility) | Windows (UI Automation) | |
|---|---|---|---|
Window named by its title, in every titleBar style |
yes (tested) | yes (tested in process) | yes (tested) |
The page reachable in native, hidden, none and transparent windows |
yes (tested) | yes (tested in process) | yes (tested) |
| Remote views reachable | yes (tested) | not tested | not tested |
| Offscreen windows left out of the tree | yes (tested) | hidden from AX (tested in process) | reported IsOffscreen, still listed |
| Menu bar and context menu: names, roles, checked, disabled, separators, accelerators | yes (tested) | yes (tested in process) | menu bar and popup items tested |
| Menus open from the keyboard | F10 and Alt+mnemonic (tested) | system | Alt and Esc (Esc tested) |
| Message dialogs: named, buttons named, default button, Esc | yes (tested) | system (default button set) | named, labels spelled out in the text |
| Tray icon always has a name | StatusNotifierItem title and tooltip | accessibility label | tip |
| Notification action buttons always have a label | yes | yes | yes |
| Split-pane divider: name, focus, arrow keys resize | yes (tested) | NSSplitView role (tested) | no keyboard access |
| Tab moves through every view of a split window | yes (tested) | system | not tested |
| Caption buttons of a hidden title bar | none drawn | traffic lights, system labels | drawn by Windows, named by it |
| Thumbnail toolbar buttons always have a name | n/a | n/a | tooltip, or the id |
#What you must do
Window titles. The title of a window is its accessible name, also when the title bar
is hidden or none and the user never sees it. Give every window a distinct, meaningful
title ("Settings", not "") and update it when the document changes.
Custom title bars. With titleBar: "none" there are no caption buttons, on any
platform. If you draw your own, make them real controls:
<header data-krate-drag>
<h1>Notes</h1>
<button aria-label="Close window" onclick="...">x</button>
</header>- Use
<button>(orrole="button"withtabindex="0") and a text label oraria-label. An icon-only<div>is invisible to a screen reader. - Controls inside a drag region stay clickable and focusable: native controls, elements
with an ARIA widget role (
button,link,tab,menuitem,checkbox,slider, ...), and elements withtabindex0 or more. A press on them is never turned into a window move. Mark a regiondata-krate-drag="false"to cut a hole in a drag region. - Do not lay an invisible drag layer over controls (an absolutely positioned
data-krate-dragelement above a button): the press reaches the layer, not the button. Put the drag attribute on the bar and leave the controls in it. - Keep the page's keyboard path complete. A drag region cannot be moved from the keyboard;
offer the window manager's shortcut, and a
Closecontrol reachable by Tab. - On Windows a
nonewindow has no system menu, so Alt+Space does nothing; Alt+F4 closes.hiddenkeeps the caption buttons, which Windows draws and names itself.
Menus. Give every item a label. Put & before the mnemonic letter ("&File"): screen
readers speak "File", and Alt+F opens it on Linux and Windows. Use accelerator so the
shortcut is announced. Disabled items are announced as unavailable.
Dialogs.
- Give a message dialog a
title(Linux, Windows) and amessage. A dialog without a title is named after its kind on Linux ("Error") and after the app on Windows. - Windows message boxes have fixed buttons (OK; Yes and No; Yes, No and Cancel). Krate names
the mapping in the box text when your labels differ ("Yes: Save, No: Discard"), and
honors
default. Two-button boxes cannot be closed with Esc; add a third button if the user must be able to dismiss without choosing. - On macOS, Esc presses only a button titled "Cancel". Name your dismiss button that.
defaultpicks the button Enter presses on every platform.
Tray. Set tooltip or title. Each stands in for the other, and with neither the
icon is named after the app, which is rarely what you want.
Notifications. A title is required. Give every action a label; an action without one
is named by its id.
Thumbnail buttons and jump lists (Windows). Set tooltip on every thumbnail button: it
is the only name the button has. A jump list task needs a title.
Split panes. On Linux each divider is a named, focusable split pane: focus it and use
the arrow keys. The views are named "Pane 1 of 2" and so on; give each page a <title>
too. On Windows the divider is mouse-only. Bind your own shortcut that calls
setDividerPosition (see Views and split panes) for keyboard users.
Focus after a dialog. The window that opened a dialog is the dialog's parent; pass its
window so focus returns to it. Dialogs without a parent return focus to wherever the
window manager puts it.
#Testing your app
Turn the screen reader on and use only the keyboard: Orca (orca) on Linux, VoiceOver
(Cmd+F5) on macOS, Narrator (Win+Ctrl+Enter) on Windows. Linux also has accerciser to
browse the AT-SPI tree. The tests Krate itself runs are in
packages/native/ACCESSIBILITY.md.
#Known gaps
- No platform was tested with a real screen reader.
- Windows: split-pane dividers have no keyboard access; frameless windows have no system menu; offscreen windows stay in the UI Automation tree (marked offscreen).
- Windows tray, thumbnail button tooltips and jump list entries are named, but the shell surfaces they appear in (notification area, taskbar thumbnail) are not read by tests.
- macOS: Esc dismisses an alert only through a "Cancel" button; the split divider is reachable by VoiceOver but not by a plain keyboard.
- Linux: the AT-SPI tests need a window manager for focus and
at-spi2-core, and run on X11 only. Wayland has not been checked.
Last updated: 2026-11-17
Contributors: Noinkin