Accessibility
Keyboard patterns, focus, reduced motion and touch targets.
This page lists what the library does, read from its source and tests. It is not a conformance claim: test your own screens with a keyboard and a screen reader. Each component page has an Accessibility section with the roles, ARIA attributes, keys and tests found for that component.
Keyboard patterns
| Pattern | Components | Keys |
|---|---|---|
| Dialog | Modal, Drawer, ReasonDialog, MobileNavSheet | Focus moves in on open and returns to the opener on close; Tab and Shift+Tab stay inside; Escape closes. With a modal over a drawer only the top layer reacts. While a Modal or Drawer is open the page behind does not scroll and is out of reach: with no inertRef the dialog makes everything outside it inert and aria-hidden (toasts and other live regions stay readable; of nested dialogs only the outermost does it) and gives back exactly what it changed before focus returns. Pass inertRef (useModalLock) when the dialog renders outside your app root and you want that one root made inert instead. |
| Tabs | PillTabs | One tab stop. ← → move (reversed under dir="rtl"), Home and End jump. activation="manual" (the default) moves focus and needs Enter or Space to select; "automatic" selects as focus moves. |
| Radio groups | FilterChips, ChoiceGroup, Segmented, ChannelPicker | role="radiogroup" with one tab stop (on the chosen option); arrow keys move and select (mirrored under dir="rtl"), and in Segmented Home and End jump to the ends. Segmented was a group of pressed buttons before 0.2.0. |
| Disclosure menus | TopbarMenu, UserMenu, NotificationsMenu | A button that opens a panel (not an ARIA menu). TopbarMenu: opening it with a click, Enter, Space or ↓ puts focus on its first item; Tab, ↑ and ↓ move through the panel (the arrows wrap, and walk in from the trigger while it is open); Escape closes it and returns focus to the trigger; a press outside, or focus leaving the menu (Tab past the last item), closes it. NotificationsMenu also traps focus while open. |
| Action menu | RowActions | A real menu for the overflow: ↓ on the "⋯" button opens it with the first item focused, arrows and Home / End move, Escape returns to the button. The open menu follows its button when the page scrolls or resizes (it closes only if the button leaves the screen). An action with confirm arms on the first press and runs on the second. Only Enter and Space (and an Escape the actions used) are kept from the row, so Tab and a surrounding dialog's trap and Escape still work. |
| Search | HeaderSearch | A combobox. No hit is highlighted until the arrows move: the first ↓ highlights the first hit and the first ↑ the last, then they wrap. Enter opens the highlighted hit (the first when none is). Escape closes the list and a second one clears the box. "No results" and "search failed" are said in a live region beside the list. |
| Disclosure | Accordion | Native <details>: Enter or Space toggles each row. |
| Switch | Switch | Space toggles. It must have a name: label, aria-labelledby (a visible label's id), or rowLabelled inside a KeyValue row's control (named by the row's label). A switch with none of them is a type error. id and aria-describedby tie it to your own label and hint. |
| Focusable tags | DecisionTag tip="focus", DecisionsCard tip="focus" | Each "Open · R10" code is a tab stop; hover or focus shows its question in a tooltip (role="tooltip", also the code's accessible description), and Escape hides it. |
| Note popover | MoneyNote | Opens on press, hover or focus; Escape closes it and puts focus back on the "?". |
Try them:
Try the keyboard
Tab to a control, then use the keys listed under it. Tabs: arrow keys, Home, End. Segmented and chips: arrow keys (Home and End in Segmented). Menu: Enter opens it and focuses the first item, Tab or arrows move, Escape closes and returns focus. Switch: Space.
Code
import { useState } from 'react';
import { Button, Drawer, FilterChips, Modal, PillTabs, Segmented, Switch, TopbarMenu, Icon } from '@ergasti/bricks';
function Keys() {
const [tab, setTab] = useState('a');
const [seg, setSeg] = useState<'7' | '30'>('7');
const [chip, setChip] = useState('all');
const [on, setOn] = useState(false);
const [modal, setModal] = useState(false);
const [drawer, setDrawer] = useState(false);
return (
<div style={{ display: 'grid', gap: 18 }}>
<PillTabs label="Demo tabs" idPrefix="a11y" value={tab} onChange={setTab}><PillTabs.Tab value="a">First</PillTabs.Tab><PillTabs.Tab value="b">Second</PillTabs.Tab><PillTabs.Tab value="c">Third</PillTabs.Tab></PillTabs>
<Segmented label="Range" value={seg} onChange={setSeg} options={[['7', '7 days'], ['30', '30 days']]} />
<FilterChips label="Status" value={chip} onChange={setChip} options={[{ value: 'all', label: 'All' }, { value: 'live', label: 'Live' }, { value: 'ended', label: 'Ended' }]} />
<label style={{ display: 'flex', gap: 10, alignItems: 'center' }}><Switch label="Notify creators" checked={on} onChange={setOn} />Notify creators</label>
<div style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
<TopbarMenu label="Help" trigger={<Icon name="help" />} items={[{ id: 'a', label: 'Copy link', keepOpen: true }, { id: 'b', label: 'Contact TRNDR' }]} />
<Button onClick={() => setModal(true)}>Open modal</Button>
<Button onClick={() => setDrawer(true)}>Open drawer</Button>
</div>
<Modal open={modal} onClose={() => setModal(false)} title="Focus is trapped here" hint="Tab cycles inside; Escape closes; focus returns to the button." footer={<Button variant="ink" onClick={() => setModal(false)}>Done</Button>}><p>Press Escape.</p></Modal>
<Drawer open={drawer} onClose={() => setDrawer(false)} title="A drawer"><p>Open a modal from here and Escape closes only the top layer.</p><Button onClick={() => setModal(true)}>Open modal over drawer</Button></Drawer>
</div>
);
}Focus
- Dialogs trap focus with
useFocusTrap, which you can use for your own panels, and restore it to the element that opened them. - Focus rings come from four tokens, drawn on
:focus-visiblefor every control family (a test lists them).--focus-ringis a 2px gap in the card colour and then a 2px raspberry ring: 5.2:1 against white, 4.6:1 against the page background. The halo it replaced was a pale tint at 1.16:1 and could not be seen.--focus-ring-insetdraws the same ring inside a box that clips its children (a scroller, a menu edge),--focus-ring-inverseis an ink gap and a white ring for controls on ink (the sidebar, the save bar, the toast), and--focus-ring-fieldis a text field's raspberry border with a soft halo. AppShellrenders a skip link that targets the main landmark (mainId); its words are the shell'sskipToMainlabel.
useFocusTrap
hook
Keeps keyboard focus inside a container while it is active: focus moves in on open and returns to the element that had it on close, Tab and Shift+Tab wrap, and Escape calls onEscape. With nested traps (a modal opened from a drawer) only the innermost one reacts. Modal and Drawer use it.
function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean, onEscape: () => void, options?: FocusTrapOptions): voidProp
Type
Source: src/hooks/useFocusTrap.ts (line 111)
Reduced motion
useReducedMotion() follows prefers-reduced-motion; the shell's phone sheet reads it. In CSS, one prefers-reduced-motion: reduce block at the end of kit.css stops the library's animations and transitions: dialogs and their scrims (also the mirrored right-to-left ones), the toast, the save bar, skeletons, popovers, the shell's sheet and menus, and hover lifts. It names the shell, blocks and PR classes too, so it applies whichever of those stylesheets you load, as long as kit.css or styles.css is loaded.
useReducedMotion
hook
Custom hook to detect whether the user has requested reduced motion via OS accessibility settings (prefers-reduced-motion: reduce).
function useReducedMotion(): booleanSource: src/hooks/useReducedMotion.ts (line 7)
Touch targets
--control-h is 44px on touch tiers (up to 1024px) and 38px on desktop, and --min-touch-target is 44px. Small controls (the steppers, matrix and table checkboxes, the pager arrows, a bulk bar's close, text-link buttons) get a 44px hit area on touch tiers by padding or an invisible hit box. DataTable's and GiftProductsPicker's checkboxes sit inside a label that is their hit area. The phone tab bar is 64px tall (--bottom-nav-height). The header's search field and breadcrumb links, GiftClaimCheck's count fields and the open-decision codes are 44px tall on touch tiers too.
Names and live regions
- Charts (
BarChartand the other chart components) arerole="img"with anaria-labelmade of the label you give;BarChartadds its total. - Tables name themselves with the
labelprop; selection checkboxes are named byrowLabel. - A
Cardwith atitle(or aCard.Header) is a region named by its heading, so screen readers list it among the page's regions. AKeyValuerow'scontrolthat does not name itself is named by the row's label. - A button that is off for a reason stays focusable:
FindCreatorCardandCreatorProfilePanelmark a disabled or busy Invite witharia-disabledand say why (inviteDisabledReason), and aButtonLinkwith an unsafehrefis a disabled-looking link with no target. - The toast region is
role="status"andaria-live="polite".ListStateandAsyncBlockdraw their errors asrole="alert". - An accessible name starts with the words on screen (WCAG 2.5.3, label in name): a
MoneyNote's button is "‹label›, what's included", and the shell's language button is "EN, English" ("عربي، العربية"). - Icons are
aria-hidden; icon-only buttons take their accessible name from a copy key (for exampledialog.close), so it is translated with everything else.