--- title: Accessibility description: The accessibility features the primitives provide, and what your application still has to supply. --- The primitives handle ARIA attributes, roles, keyboard navigation, and focus management. Because the package renders no styles, anything visual — contrast, focus indication — is your application's responsibility. ## Keyboard navigation The primitives follow the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/). The composer's editor interprets keys by mode: an open command list, or an active ask-user flow, takes priority over normal typing. A primitive that claims keys of its own documents them in a key table on its page; one that relies on native focus order does not. Anything draggable is also operable from the keyboard. The shell's grip resizes the sidebar with the arrow keys once focused, so no layout a visitor can reach with a pointer is closed to them without one. A strip or a tree is one tab stop, not one per item. Focus follows the arrow keys without selecting, which is manual activation; a primitive that should select as focus moves says so through a prop rather than by default. The nav is a roving-tabindex widget: exactly one row is tabbable and the arrow keys move focus between rows. Before that state is seeded — a server render, or the frame before hydration — the active row carries the tab stop, which keeps a row rendered as a real anchor reachable without JavaScript. A field inside the tree keeps its own arrow keys, or its caret could never move. A scroll surface has to be reachable before it can be scrolled. The thread's viewport is a focusable `role="region"` named "Messages" by default, so a keyboard user can Tab to it and use the usual keys. Only the upward keys — `ArrowUp`, `PageUp` and `Home` — are intercepted, to release auto-follow; scrolling down never does, because releasing it at the bottom would leave the view unfollowed while pinned there. Announce additions, not mutations. The thread's content column is a `role="log"` with `aria-relevant="additions"`, so a turn announces when its row is added and tokens streaming into an existing row deliberately do not re-announce. Token-by-token narration is noise. If an end-of-response announcement is wanted, add your own `role="status"` region that flips on completion. Motion preferences are honoured for programmatic scrolls. Anything the thread requests as smooth, including auto-follow, downgrades to instant when the operating system asks for reduced motion. Command lists and ask-user options move a highlight rather than DOM focus, so the caret stays in the editor while you navigate. Arrowing past the end of a list keeps focus in place; arrowing up past the first ask-user option returns to the editor. ## Focus management Focus is managed automatically after interaction — the composer restores the caret after selecting a command item, and ask-user recovers arrow navigation if a click elsewhere drops focus to the body. In command lists and ask-user options the highlight *is* the focus indication — focus follows it rather than moving separately, so styling the highlight faintly removes the focus indicator rather than softening a hover effect. ## Roles and relationships The composer's editor is wired to its command list as a combobox: `aria-autocomplete="list"` and `aria-haspopup="listbox"`, plus `aria-controls` and `aria-activedescendant` while a popup is open. The popup is a `listbox` named "Suggestions" whose rows carry stable ids and `aria-selected`; selection stays in the editor, so rows are never tab stops. Grouped lists wrap in `role="group"` named by their label, async resolution sets `aria-busy`, and the empty state is a `role="status"` region. That pattern deviates from the APG combobox in one place, deliberately. `aria-expanded` is omitted because ARIA 1.2 forbids it on `textbox`, and moving to `role="combobox"` would forbid `aria-multiline`, which matters more for a chat field that wraps. The popup announces through `aria-haspopup` and live `aria-activedescendant` narration instead, and Tab selects the highlighted option rather than moving focus. Ask-user renders a labelled `radiogroup`, or `role="group"` with checkboxes for multi-select. Each option is the real control, holding the group's single tab stop through roving `tabindex`, so never nest an interactive control inside one: the option *is* the control, and the composer's question mode treats native inputs as foreign editables. Disabled options are announced but skipped by highlight and selection. A placeholder overlay is decoration. The composer's is `aria-hidden`, and the string reaches assistive technology through `aria-placeholder` instead — so when rich `children` replace the string visually, keep the `placeholder` string alongside or the hint stops announcing. Clicking chrome should not create a tab stop. The composer's container is a mouse-only focus passthrough: clicking it focuses the editor, clicks on nested buttons and links pass through, and it carries no role, so keyboard users tab straight to the editor. `Steps` marks the active item with `aria-current="step"`. A disclosure built for streaming says so while it runs: `Reasoning.Root` carries `aria-busy` until `isStreaming` flips false, so assistive technology knows the text underneath is still arriving rather than finished. Disclosure controls announce both their state and what they govern: the shell's trigger is a `