Accessibility and overlays

This guide documents the admin-first layered UI system introduced for #136 and the blocking accessibility checks introduced for #141.

Overlay decision tree

Use the lightest surface that matches the job:

• Tooltip

  • Use for short non-interactive help on hover and focus.
  • Do not trap focus.
  • Do not use for form fields or multi-step guidance.

• Popover

  • Use for anchored supporting UI such as filter panels, column choosers, and lightweight action surfaces.
  • Do not trap focus.
  • Close on outside interaction or Tab.

• ContextMenu

  • Use for row-level or card-level secondary actions opened from right click, keyboard context-menu invocation, or long press.
  • Keep actions concise and destructive items clearly separated.

• Modal

  • Use for blocking task flows, forms, and focused review work.
  • Trap focus and restore it on close.

• AlertDialog

  • Use for confirmation and destructive decisions.
  • Keep the copy explicit.
  • Button order in admin web stays Cancel then the confirm/destructive action.

• Panel

  • Use for large edge-anchored workspaces such as the assistant shell drawer.
  • Treat blocking panels like dialogs for focus and dismissal.

• Sheet

  • Use for partial-height mobile-style presentations on narrow screens when the task is too large for a popover but does not need a full modal.

Accessibility test matrix

The blocking browser audit covers representative admin states:

• shell and dashboard baseline
• a dense list/table page
• a modal/dialog state
• a popover/action-menu state
• an account/settings page

The blocking repo checks also cover:

• token-pair contrast expectations for the shipped admin theme surfaces
• new raw z-index declarations outside the explicit legacy allowlist
• forced-colors/high-contrast browser states for the shell, modal, table, and popover flows
• 200% text zoom smoke coverage for the same representative admin flows
• mobile touch-target drift in new React Native Pressable and Touchable* usage

Local commands

Run these before pushing overlay or accessibility changes:

npm run test:admin-accessibility
npm run check:admin-contrast
npm run check:admin-z-index
npm run check:mobile-touch-targets
npm run test:admin-browser
npm run test:admin-layout
npm run check:admin-release

Screen-reader and touch matrix

Use this matrix for VoiceOver, TalkBack, and touch-target spot checks when a change touches one of these surfaces.

Review prompts

When reviewing layered UI changes, check these behaviors explicitly:

• repeated Esc closes only the topmost surface
• focus returns to the launcher after closing dialogs and panels
• popovers and menus do not trap keyboard users
• shell controls stay readable and operable at 200% text zoom
• forced-colors mode preserves boundaries and focus indication