Accessibility
Accessibility principles, keyboard interaction models, and ARIA contracts in Moraine.
Moraine implements keyboard navigation, focus management, and ARIA relationships based on the W3C WAI-ARIA Authoring Practices. Applications still need accessible names, readable color contrast, and appropriate semantics for custom renderers and polymorphic elements.
Keyboard Interaction Models#
Moraine components follow established UI patterns for keyboard interaction:
Collection Navigation#
Tabs uses roving tabindex: the highlighted tab has tabindex="0", and other tab triggers have tabindex="-1". Select-family controls keep DOM focus on their trigger or input and identify the highlighted option through aria-activedescendant. Menus move focus between their items. These models support arrow navigation without adding every option to the page’s tab order:
| Key | Action |
|---|---|
| ↓ / → | Moves to the next item along the component’s navigation axis. |
| ↑ / ← | Moves focus to the previous item. |
| ↖ | Moves focus directly to the first enabled item. |
| ↘ | Moves focus directly to the last enabled item. |
| ↵ / Space | Activates or selects where supported; editable inputs retain normal text entry. |
Looping and activation depend on the component and its options. See each component’s keyboard documentation for orientation, disabled items, typeahead, and selection.
Overlay Dismissal#
Dismissible overlays (such as Dialog, Sheet, Drawer, Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, and select popups) close on Esc. Only the topmost active overlay handles the key, so closing a nested overlay leaves its parent open. Escape is ignored during IME composition. Set closeOnEscape to false to keep an overlay open; onClosePrevented reports the blocked attempt.
Focus Management#
Focus Trapping in Modals#
Modal surfaces such as Dialog, Sheet, Drawer, and BaseDialog keep keyboard focus inside their content while open. Tabbing past the last focusable element returns focus to the first. While open, they also hide outside content from assistive technology and lock page scroll. Popover is non-modal by default; modal applies the same behavior only when the content includes Popover.Close. With modal={false} on a modal surface, focus is not trapped, moved on open, or restored on close.
Focus Restoration#
Modal overlays restore focus to their trigger after closing, or to the element that was focused when they opened. Set finalFocus to choose another element. Non-modal floating overlays restore focus after keyboard dismissal but let an outside press move focus to its target. Tooltips never move focus from their trigger. Check each component’s focus options before customizing this behavior.
Initial Auto-Focus#
Modal surfaces focus an [autofocus] or [data-autofocus] descendant when opened, otherwise the first focusable child, otherwise the content container. When opened by touch, they focus the content container. Set initialFocus to choose the element, or false to skip the move. Menus and select-family controls use their own highlighted-item behavior. Tooltips do not move focus into their content.
ARIA Attribute Contracts#
Moraine sets and updates these ARIA attributes from component state:
- State indication: Components maintain
aria-expanded="true|false"on triggers,aria-selected="true|false"on selection items, andaria-checked="true|false|mixed"on checkboxes. - Relationship wiring: Triggers and contents are linked through
aria-controlswith deterministic element IDs generated bycreateId. - Overlay names:
Dialog.ContentandSheet.Contentusetitleasaria-labelledby(unlessaria-labelis set) anddescriptionasaria-describedby.BaseDialog.Contentrendersrole="dialog"and needs anaria-labeloraria-labelledby. - Form association:
Fieldbinds itslabelto the registered control througharia-labelledby, and itshint,description,error, andhelptext througharia-describedby.hiddenLabelsupplies a visually hidden label whenlabelis empty. - Validation: When a field has an error, Moraine sets
aria-invalid="true"on the control and adds the visible error message toaria-describedby.
Screen Reader Considerations#
-
Semantic HTML: Moraine uses native controls such as
<button>and<input>alongside ARIA roles for custom widgets and overlay surfaces. When you use theasprop, the rendered element must provide the same semantics. -
Icon-only buttons: Provide an accessible name with
aria-label: -
Built-in labels: Accessible names that Moraine supplies, such as the
Dialogclose button, come from locale messages. Override them with a component’stranslationsprop orMoraineProvidermessages; see the Localization guide.