Skip to Content
BBRICKSv0.7.4
Foundations

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

PatternComponentsKeys
DialogModal, Drawer, ReasonDialog, MobileNavSheetFocus 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.
TabsPillTabsOne 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 groupsFilterChips, ChoiceGroup, Segmented, ChannelPickerrole="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 menusTopbarMenu, UserMenu, NotificationsMenuA 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 menuRowActionsA 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.
SearchHeaderSearchA 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.
DisclosureAccordionNative <details>: Enter or Space toggles each row.
SwitchSwitchSpace 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 tagsDecisionTag 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 popoverMoneyNoteOpens 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-visible for every control family (a test lists them). --focus-ring is 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-inset draws the same ring inside a box that clips its children (a scroller, a menu edge), --focus-ring-inverse is an ink gap and a white ring for controls on ink (the sidebar, the save bar, the toast), and --focus-ring-field is a text field's raspberry border with a soft halo.
  • AppShell renders a skip link that targets the main landmark (mainId); its words are the shell's skipToMain label.

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): void

Prop

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(): boolean

Source: 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 (BarChart and the other chart components) are role="img" with an aria-label made of the label you give; BarChart adds its total.
  • Tables name themselves with the label prop; selection checkboxes are named by rowLabel.
  • A Card with a title (or a Card.Header) is a region named by its heading, so screen readers list it among the page's regions. A KeyValue row's control that does not name itself is named by the row's label.
  • A button that is off for a reason stays focusable: FindCreatorCard and CreatorProfilePanel mark a disabled or busy Invite with aria-disabled and say why (inviteDisabledReason), and a ButtonLink with an unsafe href is a disabled-looking link with no target.
  • The toast region is role="status" and aria-live="polite". ListState and AsyncBlock draw their errors as role="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 example dialog.close), so it is translated with everything else.

On this page