[P1] Create an accessible dialog, navigation, and form foundation

[postigodev]

Context

The frontend has many custom overlays and controls, but accessibility behavior is implemented inconsistently. Major modals are fixed div/section overlays without a shared dialog contract, focus trap, Escape handling, focus restoration, or inert background. Active navigation and tab-like controls also rely primarily on color, while several forms lack explicit labels and field-level accessible errors.

The current color tokens additionally use white text on orange combinations that do not meet WCAG AA contrast for common text sizes.

Accessibility should be solved through shared primitives and semantic tokens rather than one-off patches in every screen.

Scope

• Create or adopt shared accessible primitives for dialog, alert dialog, menu/popover, combobox/listbox, tabs/segmented controls, and live feedback.
• Ensure dialogs provide an accessible name, aria-modal, focus containment, sensible initial focus, Escape handling, background inertness, scroll lock, and focus restoration.
• Migrate launch-critical overlays: recipe capture/editor, camera, voice inventory, hands-free setup/mode, meal-event editor, and mobile create menu.
• Add aria-current to active navigation and aria-selected/aria-pressed semantics to tab and toggle groups.
• Associate every form label, description, error, and required state with its control.
• Give icon-only and destructive controls explicit accessible names.
• Add role="alert"/aria-live behavior for async errors and status changes where appropriate.
• Replace failing foreground/background token pairs with semantic action tokens that meet WCAG AA.
• Add a global prefers-reduced-motion strategy and avoid essential information conveyed only through animation or color.
• Review minimum text sizes, touch targets, zoom/reflow, and high-contrast behavior.
• Add automated and manual accessibility verification to [P0] Add launch-critical validation and staging smoke tests to dev and release CI #77.

Acceptance criteria

• Launch-critical dialogs trap focus, close with Escape where appropriate, restore focus, and make background content inert.
• Keyboard-only users can operate navigation, menus, comboboxes, tabs, forms, camera/voice setup, and destructive confirmations.
• Active navigation and selected controls expose semantic state to assistive technology.
• Inputs have programmatic labels and errors use aria-invalid/aria-describedby or an equivalent pattern.
• Icon-only controls have accurate accessible names.
• Core text/action color combinations meet WCAG 2.2 AA contrast.
• Reduced-motion users do not receive unnecessary continuous or entrance animation.
• axe checks pass on critical routes with documented exceptions only.
• Manual checks cover VoiceOver, TalkBack, 200% zoom/reflow, keyboard focus order, and high contrast.
• Shared primitives are documented so new UI does not reintroduce bespoke inaccessible overlays.

Related

• Launch-critical CI and browser validation: [P0] Add launch-critical validation and staging smoke tests to dev and release CI #77.
• App-wide async/error states: [P1] Establish app-wide loading, error, offline, and stale-data states #113.
• Recipe editor stabilization: tracked separately.
• Hands-free gating and disclosure: [P0] Enforce real hands-free audio gating and accurate microphone states #111 and [P0] Publish privacy, terms, AI, and voice disclosures before public beta #99.

Out of scope

• A full visual redesign of Preppie.
• Claiming formal accessibility certification without an external audit.