Skip to content

feat(accessibility): add ARIA semantics and landmark roles#594

Open
baich110 wants to merge 15 commits into
OpenListTeam:mainfrom
baich110:accessibility-improvements
Open

feat(accessibility): add ARIA semantics and landmark roles#594
baich110 wants to merge 15 commits into
OpenListTeam:mainfrom
baich110:accessibility-improvements

Conversation

@baich110

Copy link
Copy Markdown

Summary

This PR implements comprehensive accessibility (a11y) improvements for the OpenList frontend, based on a file-by-file source code audit. The changes address critical barriers that prevent TalkBack (Android screen reader) users from using the app's core features.

Related issues: #2800 (Chinese) / #2801 (English)

Problem

OpenList's Android app renders its UI through a WebView. While the Web interface works functionally, interactive elements lacked ARIA semantic annotations, making the app nearly unusable for visually impaired users who rely on screen readers. A full-project audit found only ~25 aria-label instances, concentrated in image preview controls, with zero coverage in core interaction areas (file list, context menu, toolbar).

Changes

P0 - Critical (File List & Context Menu)

src/pages/home/folder/ListItem.tsx

  • Added role="listitem" + aria-label to list item container (merges filename, size, type, and modified date into one announceable unit)
  • Added tabIndex={0} for keyboard focus
  • Added aria-label to selection checkbox

src/pages/home/folder/GridItem.tsx

  • Added role="listitem" + aria-label to grid item container
  • Added tabIndex={0} for keyboard focus
  • Added alt attribute to thumbnail images
  • Added aria-label to selection checkbox

src/pages/home/folder/context-menu.tsx

  • Added aria-label to menu container
  • Added aria-label to all menu items (rename, move, copy, delete, share, decompress)

P1 - High (Semantic Structure & Toolbar)

src/pages/home/folder/List.tsx

  • Added role="list" to list container
  • Added role="button", tabIndex={0}, aria-label to sort column headers
  • Added aria-label to select-all checkbox

src/pages/home/Layout.tsx

  • Wrapped main content in <Box as="main" role="main"> for landmark navigation

src/pages/home/header/Header.tsx

  • Added role="banner" to header

src/pages/home/Nav.tsx

  • Added role="navigation" + aria-label to breadcrumb navigation

src/pages/home/toolbar/Icon.tsx

  • Added aria-label + tabIndex={0} to CenterIcon (rename, move, copy, delete, decompress, share, cancel select, download)
  • Added aria-label + tabIndex={0} to RightIcon (refresh, new file, mkdir, upload, offline download, settings, etc.)

src/pages/home/toolbar/BackTop.tsx

  • Added aria-label + tabIndex={0} to back-to-top button

P2 - Medium (Dynamic Content & UI Controls)

src/utils/notify.tsx

  • Added role="status" + aria-live="polite" to notification container (Toast notifications now announced by screen readers)

src/components/FullLoading.tsx

  • Added role="status" + aria-busy="true" + aria-label to loading spinners

src/components/SwitchColorMode.tsx

  • Added aria-label + tabIndex={0} to color mode toggle

src/pages/home/Password.tsx

  • Added aria-label to password input

P3 - Low (HTML Structure)

index.html

  • Added skip-to-main-content link for keyboard navigation

src/app/App.tsx

  • Added aria-hidden="true" to routing progress bar (decorative)

Impact

  • Before: ~25 aria-label instances, core interaction areas completely blank
  • After: ~88 accessibility attributes across 15 files, covering file list, context menu, toolbar, page landmarks, notifications, and loading states
  • TalkBack users can now: browse file lists with announced filenames/sizes/dates, understand toolbar button functions, receive notification feedback, and use landmark navigation

Testing

Unable to build locally in this environment. The changes are purely additive ARIA attributes and semantic HTML -- no logic changes. Recommend testing with:

  • TalkBack on Android (primary target)
  • NVDA on desktop browser
  • axe DevTools for automated validation

Background

We are from the Chinese visually impaired community (20,000+ visually impaired developers, 200,000+ users). We conducted a full source code audit of both the backend and frontend, with all issues documented in #2800/#2801. This PR implements the fixes for the documented issues.

@jyxjjj jyxjjj changed the title [Accessibility] Add ARIA semantics and landmark roles for TalkBack/screen reader support feat(accessibility): add ARIA semantics and landmark roles Jul 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] 希望前端可以对无障碍方面做优化

1 participant