Refactor Modal components to implement strict ARIA accessibility standards

[Lakes41]

Difficulty: Intermediate
Type: UI/UX, accessibility

Background

The application heavily utilizes popup modals for confirmations, settings, and token selections. These were built quickly using basic absolute positioning.

Problem

The current modals trap visual focus but lack proper ARIA attributes, meaning screen readers cannot properly announce the modal's presence, title, or purpose to visually impaired users.

Expected outcome

All primary modals are updated to strictly adhere to W3C WAI-ARIA authoring practices for Dialog (Modal) widgets.

Suggested implementation

1. Add role="dialog" and aria-modal="true" to the modal wrappers.
2. Ensure the modal container includes aria-labelledby pointing to the modal's title ID, and aria-describedby pointing to its body ID.
3. Verify that focus is actively trapped within the modal while open, and restored to the trigger element when closed.

Acceptance criteria

• Screen readers properly announce the modal when it opens.
• Users can navigate through all modal elements using only the Tab key.
• Pressing Escape reliably closes the modal.

Likely affected files/directories

• src/components/UI/Modal.tsx

Requirements

• Consider migrating to @radix-ui/react-dialog primitives if the custom implementation is too brittle.

[Paranoa-dev]

I’d like to take this on. I have experience building accessible React component libraries and improving modal implementations using WAI-ARIA best practices, including focus management, keyboard navigation, and screen reader support.

For this issue, I'll audit the existing modal implementation and update it to comply with the W3C Dialog (Modal) authoring practices. I'll add the appropriate accessibility attributes (role="dialog", aria-modal="true", aria-labelledby, and aria-describedby), implement robust focus trapping while the modal is open, restore focus to the triggering element when it closes, and ensure the Escape key consistently dismisses the dialog where appropriate.

If the current custom implementation proves difficult to maintain, I'll evaluate migrating it to @radix-ui/react-dialog while preserving the existing API and behavior. I'll also add focused component tests covering keyboard navigation, focus trapping, Escape handling, and accessibility attributes to prevent regressions.

Before submitting the PR, I'll verify the modals with keyboard-only navigation and screen-reader accessibility checks, run the project's lint and test suite, and ensure the implementation remains backward compatible and easy to review.