Development: Accessibility

Joplin has a strong focus on accessibility. It's important to make sure that new pull requests and features keep Joplin accessible.

Making new components accessible

When creating new components, it's important to make sure that they're accessible. How to do this varies a bit between desktop and mobile, but in general:

• All focusable controls should have labels. (Usually, these labels are provided by text inside the controls.)
• Buttons should be at least 24px by 24px.
• The app should be keyboard-accessible.
• The app should be usable from a screen reader
• Controls should have sufficient contrast.
  • See the WebAIM contrast checker.

For a full list of accessibility guidelines, see the WCAG 2.2.

For more information, see:

• Resources for HTML:
  • Providing Accessible Names and Descriptions.
  • Standard keyboard and ARIA for different component types.
  • Developing a Keyboard Interface.
• Resources for React Native:
  • React Native lists accessibility-related properties in its documentation.

Testing with a screen reader

Joplin should be accessible to screen readers. A big part of this is testing changes to the UI with a screen reader. Here's how to do that.

Desktop: Setting up a screen reader

Most systems have a built-in screen reader that can be enabled and disabled in settings, or with keyboard shortcuts:

• Windows:
  • Windows Narrator comes with Windows.
  • NVDA is a popular OpenSource screen reader for Windows. It doesn't come with Windows and must be downloaded.
• MacOS:
  • VoiceOver comes with MacOS.
• Linux:
  • Many Linux systems come with the Orca screen reader. It's often possible to launch it from the command line by running orca.

Each of these screen readers has its own keyboard shortcuts and navigation methods. In general, however, it's possible to use keyboard shortcuts such as <kbd>tab</kbd> and <kbd>shift</kbd>-<kbd>tab</kbd> to navigate while a screen reader is enabled. See the documentation links above for documentation specific to each screen reader.

Notes:

• Joplin works best if the screen reader is started before launching the app.
• Screen readers usually have shortcuts for jumping to different parts of the page, including headings and landmarks. See the ARIA Authoring Practices Guide for a list of these shortcuts for different screen readers.
• Screen readers often have different focus and browse modes.
  • Focus mode is used, for example, when typing text in a text box. Keypresses are sent to the textbox rather than being interpreted as screen reader commands.
  • In browse mode, keyboard shortcuts can be used to more quickly jump between different parts of the page. For example, in the Orca screen reader, pressing <kbd>b</kbd> jumps to the next button, but only in browse mode.
  • See also NVDA browse and focus modes, Orca: Filling out forms (discusses browse and focus modes).

Mobile: Setting up a screen reader

Like desktop, most physical Android and iOS devices come with screen readers. However, setting up a screen reader on an Android emulator or iOS simulator can be a bit more difficult:

• Physical Android device:
  • Android devices usually come with TalkBack.
  • See developer.android.com's guide for testing with TalkBack.
• Physical iOS device:
  • iOS comes with VoiceOver.
• iOS simulator:
  1. Start the simulator.
  2. Enable VoiceOver for MacOS.
  3. Focus the simulator's window.
  4. Press <kbd>control</kbd>-<kbd>option</kbd>-<kbd>rightArrow</kbd> repeatedly to move VoiceOver focus into the simulator.
     • Note: Sometimes, VoiceOver reads "Simulator not responding" before allowing VoiceOver focus to be moved into the simulator.
• Android emulator:
  • On Android, it may be necessary to install TalkBack from the Google Play Store (in an emulator with the Play Store installed) or build a TalkBack APK from source.
  • After installation, TalkBack can be enabled as on a physical Android device, from the settings app.
• Web:
  • Enable the operating system's screen reader (see "Desktop: Setting up a screen reader").

On a physical mobile device, VoiceOver and TalkBack share certain gestures:

• To focus the next item: Swipe from left to right.
• To focus the previous item: Swipe from right to left.
• To jump focus to a particular part of the screen: Tap once on the part of the screen to focus.
• To click on the focused item: Double-tap anywhere on the screen.

Adding automated tests to prevent regressions

The desktop and mobile apps use different frameworks for checking for accessibility-related regressions: The desktop app uses Playwright and the mobile app uses react-native-testing-library.

Desktop: Automated accessibility testing

Existing Playwright automated tests can be found in packages/app-desktop/integration-tests. See the integration-tests/README.md file for details.

For general accessibility issues (e.g. contrast, missing labels), we use @axe-core/playwright. This library scans everything visible on the screen and returns a set of errors. See integration-tests/wcag.spec.ts for existing tests that make use of this library.

Keyboard interface tests should go in the other test files. For example, richText.spec.ts currently includes several tests related to using the editor with a keyboard. While writing these tests, the expect.toBeFocused, keyboard.press, and getByRole APIs might be particularly useful.

The getByRole API can also be used to verify that components have specific role information.

Mobile: Automated accessibility testing

On mobile, react-native-testing-library also provides a getByRole selector that can be used to ensure that accessibility information is present. See, for example, this test for list of installed plugins.